System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact b590133adb2907b8b635c5df4c88393ea94761bd:


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 6e  -in (UTC) and an
1090: 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66   SHA1.** hash of
10a0: 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72   the entire sour
10b0: 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53  ce tree..**.** S
10c0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
10d0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c  3_libversion()],
10e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  .** [sqlite3_lib
10f0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
1100: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72  ], [sqlite3_sour
1110: 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ceid()],.** [sql
1120: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
1130: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
1140: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  e_id()]..*/.#def
1150: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ine SQLITE_VERSI
1160: 4f 4e 20 20 20 20 20 20 20 20 22 33 2e 31 37 2e  ON        "3.17.
1170: 30 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0".#define SQLIT
1180: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1190: 20 33 30 31 37 30 30 30 0a 23 64 65 66 69 6e 65   3017000.#define
11a0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
11b0: 44 20 20 20 20 20 20 22 32 30 31 37 2d 30 32 2d  D      "2017-02-
11c0: 31 33 20 31 36 3a 30 32 3a 34 30 20 61 64 61 30  13 16:02:40 ada0
11d0: 35 63 66 61 38 36 61 64 37 66 35 36 34 35 34 35  5cfa86ad7f564545
11e0: 30 61 63 37 61 32 61 32 31 63 39 61 61 36 65 35  0ac7a2a21c9aa6e5
11f0: 37 64 32 63 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  7d2c"../*.** CAP
1200: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
1210: 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20  Library Version 
1220: 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f  Numbers.** KEYWO
1230: 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72  RDS: sqlite3_ver
1240: 73 69 6f 6e 20 73 71 6c 69 74 65 33 5f 73 6f 75  sion sqlite3_sou
1250: 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  rceid.**.** Thes
1260: 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f  e interfaces pro
1270: 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e  vide the same in
1280: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65  formation as the
1290: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
12a0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  ],.** [SQLITE_VE
12b0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61  RSION_NUMBER], a
12c0: 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  nd [SQLITE_SOURC
12d0: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
12e0: 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62  ssor macros.** b
12f0: 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65  ut are associate
1300: 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61  d with the libra
1310: 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ry instead of th
1320: 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20  e header file.  
1330: 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72  ^(Cautious.** pr
1340: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20  ogrammers might 
1350: 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28 29  include assert()
1360: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
1370: 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  heir application
1380: 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68   to.** verify th
1390: 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  at values return
13a0: 65 64 20 62 79 20 74 68 65 73 65 20 69 6e 74 65  ed by these inte
13b0: 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 68 65  rfaces match the
13c0: 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68   macros in.** th
13d0: 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68  e header, and th
13e0: 75 73 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  us ensure that t
13f0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1400: 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
1410: 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72  th matching libr
1420: 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 20 66  ary and header f
1430: 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  iles..**.** <blo
1440: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1450: 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 65 33   assert( sqlite3
1460: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1470: 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52  er()==SQLITE_VER
1480: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a  SION_NUMBER );.*
1490: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
14a0: 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69  (sqlite3_sourcei
14b0: 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43  d(),SQLITE_SOURC
14c0: 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61  E_ID)==0 );.** a
14d0: 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71  ssert( strcmp(sq
14e0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
14f0: 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  (),SQLITE_VERSIO
1500: 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72  N)==0 );.** </pr
1510: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1520: 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1530: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
1540: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63  tring constant c
1550: 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74  ontains the text
1560: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53   of [SQLITE_VERS
1570: 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20  ION].** macro.  
1580: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62  ^The sqlite3_lib
1590: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69  version() functi
15a0: 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  on returns a poi
15b0: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74  nter to the.** t
15c0: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65  o the sqlite3_ve
15d0: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
15e0: 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71  onstant.  The sq
15f0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1600: 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  ().** function i
1610: 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75  s provided for u
1620: 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65  se in DLLs since
1630: 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c   DLL users usual
1640: 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a  ly do not have.*
1650: 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20  * direct access 
1660: 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  to string consta
1670: 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44  nts within the D
1680: 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  LL.  ^The.** sql
1690: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
16a0: 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f  number() functio
16b0: 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  n returns an int
16c0: 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a  eger equal to.**
16d0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
16e0: 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20  _NUMBER].  ^The 
16f0: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
1700: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
1710: 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  rns .** a pointe
1720: 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f  r to a string co
1730: 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c  nstant whose val
1740: 75 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  ue is the same a
1750: 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  s the .** [SQLIT
1760: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70  E_SOURCE_ID] C p
1770: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1780: 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  o..**.** See als
1790: 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69  o: [sqlite_versi
17a0: 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
17b0: 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a  e_source_id()]..
17c0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  */.SQLITE_API SQ
17d0: 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73  LITE_EXTERN cons
17e0: 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76  t char sqlite3_v
17f0: 65 72 73 69 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45  ersion[];.SQLITE
1800: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
1810: 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  *sqlite3_libvers
1820: 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ion(void);.SQLIT
1830: 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
1840: 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65   *sqlite3_source
1850: 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  id(void);.SQLITE
1860: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1870: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1880: 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  er(void);../*.**
1890: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
18a0: 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70  ime Library Comp
18b0: 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20  ilation Options 
18c0: 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a  Diagnostics.**.*
18d0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
18e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
18f0: 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  d() function ret
1900: 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20  urns 0 or 1 .** 
1910: 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74 68  indicating wheth
1920: 65 72 20 74 68 65 20 73 70 65 63 69 66 69 65 64  er the specified
1930: 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69   option was defi
1940: 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69  ned at .** compi
1950: 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53  le time.  ^The S
1960: 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61  QLITE_ prefix ma
1970: 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f  y be omitted fro
1980: 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e  m the .** option
1990: 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20   name passed to 
19a0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
19b0: 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a  ption_used().  .
19c0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
19d0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
19e0: 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  _get() function 
19f0: 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67  allows iterating
1a00: 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73  .** over the lis
1a10: 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61  t of options tha
1a20: 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 20 61  t were defined a
1a30: 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62  t compile time b
1a40: 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74  y.** returning t
1a50: 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20  he N-th compile 
1a60: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69  time option stri
1a70: 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75  ng.  ^If N is ou
1a80: 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73  t of range,.** s
1a90: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1aa0: 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72  tion_get() retur
1ab0: 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1ac0: 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  r.  ^The SQLITE_
1ad0: 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f   .** prefix is o
1ae0: 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20  mitted from any 
1af0: 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
1b00: 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
1b10: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b20: 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70  t()..**.** ^Supp
1b30: 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 61 67  ort for the diag
1b40: 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73  nostic functions
1b50: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1b60: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a  option_used().**
1b70: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d   and sqlite3_com
1b80: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1b90: 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20   may be omitted 
1ba0: 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 74 68  by specifying th
1bb0: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d  e .** [SQLITE_OM
1bc0: 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e  IT_COMPILEOPTION
1bd0: 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61  _DIAGS] option a
1be0: 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a  t compile time..
1bf0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
1c00: 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73  SQL functions [s
1c10: 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74  qlite_compileopt
1c20: 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ion_used()] and.
1c30: 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69  ** [sqlite_compi
1c40: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20  leoption_get()] 
1c50: 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65  and the [compile
1c60: 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d  _options pragma]
1c70: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
1c80: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1c90: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51 4c  OPTION_DIAGS.SQL
1ca0: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1cb0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1cc0: 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61  n_used(const cha
1cd0: 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53 51  r *zOptName);.SQ
1ce0: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
1cf0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1d00: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1d10: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1d20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1d30: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1d40: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1d50: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1d60: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1d70: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1d80: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1d90: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1da0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1db0: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1dc0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1dd0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1de0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1df0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1e00: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1e10: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1e20: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1e30: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1e40: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1e50: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1e60: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1e70: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1e80: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1e90: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1ea0: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1eb0: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1ec0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1ed0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1ee0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1ef0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1f00: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1f10: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
1f20: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
1f30: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
1f40: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
1f50: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
1f60: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
1f70: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
1f80: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
1f90: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
1fa0: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
1fb0: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
1fc0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
1fd0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
1fe0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
1ff0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
2000: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
2010: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2020: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2030: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2040: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2050: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2060: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2070: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2080: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2090: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
20a0: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
20b0: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
20c0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
20d0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
20e0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
20f0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
2100: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
2110: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2120: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2130: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2140: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2150: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2160: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2170: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2180: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2190: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
21a0: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
21b0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
21c0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
21d0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
21e0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
21f0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
2200: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
2210: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2220: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2230: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2240: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2250: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2260: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2270: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2280: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2290: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
22a0: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
22b0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
22c0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
22d0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
22e0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
22f0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
2300: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
2310: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2320: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2330: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2340: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2350: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2360: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2370: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2380: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2390: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
23a0: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
23b0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
23c0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
23d0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
23e0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
23f0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
2400: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
2410: 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
2420: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2430: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29  threadsafe(void)
2440: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2450: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
2460: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a  ection Handle.**
2470: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61   KEYWORDS: {data
2480: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d  base connection}
2490: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
24a0: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61  ctions}.**.** Ea
24b0: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
24c0: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
24d0: 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e  sented by a poin
24e0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
24f0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61  ce of.** the opa
2500: 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61  que structure na
2510: 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20  med "sqlite3".  
2520: 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20  It is useful to 
2530: 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69  think of an sqli
2540: 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61  te3.** pointer a
2550: 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68  s an object.  Th
2560: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
2570: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2580: 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  n16()], and.** [
2590: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25a0: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  )] interfaces ar
25b0: 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f  e its constructo
25c0: 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  rs, and [sqlite3
25d0: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64  _close()].** and
25e0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
25f0: 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65  v2()] are its de
2600: 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72  structors.  Ther
2610: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
2620: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28  .** interfaces (
2630: 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69  such as.** [sqli
2640: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2650: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
2660: 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
2670: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2680: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
2690: 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65  to name but thre
26a0: 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68  e) that are meth
26b0: 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c  ods on an.** sql
26c0: 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ite3 object..*/.
26d0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
26e0: 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a  qlite3 sqlite3;.
26f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2700: 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20   64-Bit Integer 
2710: 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Types.** KEYWORD
2720: 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  S: sqlite_int64 
2730: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a  sqlite_uint64.**
2740: 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72  .** Because ther
2750: 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c  e is no cross-pl
2760: 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70  atform way to sp
2770: 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74  ecify 64-bit int
2780: 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51  eger types.** SQ
2790: 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79  Lite includes ty
27a0: 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69  pedefs for 64-bi
27b0: 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73  t signed and uns
27c0: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a  igned integers..
27d0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
27e0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
27f0: 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74  te3_uint64 are t
2800: 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70  he preferred typ
2810: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a  e definitions..*
2820: 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74  * The sqlite_int
2830: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
2840: 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73  nt64 types are s
2850: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63  upported for bac
2860: 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74  kwards.** compat
2870: 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a  ibility only..**
2880: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2890: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
28a0: 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  e_int64 types ca
28b0: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
28c0: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
28d0: 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34  n -9223372036854
28e0: 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33  775808 and +9223
28f0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20  372036854775807 
2900: 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65  inclusive.  ^The
2910: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  .** sqlite3_uint
2920: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
2930: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
2940: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2950: 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20  ues .** between 
2960: 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30  0 and +184467440
2970: 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c  73709551615 incl
2980: 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66  usive..*/.#ifdef
2990: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
29a0: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c  PE.  typedef SQL
29b0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
29c0: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 23 20 69  qlite_int64;.# i
29d0: 66 64 65 66 20 53 51 4c 49 54 45 5f 55 49 4e 54  fdef SQLITE_UINT
29e0: 36 34 5f 54 59 50 45 0a 20 20 20 20 74 79 70 65  64_TYPE.    type
29f0: 64 65 66 20 53 51 4c 49 54 45 5f 55 49 4e 54 36  def SQLITE_UINT6
2a00: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69  4_TYPE sqlite_ui
2a10: 6e 74 36 34 3b 0a 23 20 65 6c 73 65 20 20 0a 20  nt64;.# else  . 
2a20: 20 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67     typedef unsig
2a30: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  ned SQLITE_INT64
2a40: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e  _TYPE sqlite_uin
2a50: 74 36 34 3b 0a 23 20 65 6e 64 69 66 0a 23 65 6c  t64;.# endif.#el
2a60: 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f  if defined(_MSC_
2a70: 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28  VER) || defined(
2a80: 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20  __BORLANDC__).  
2a90: 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20  typedef __int64 
2aa0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
2ab0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
2ac0: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 sqlite_
2ad0: 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20  uint64;.#else.  
2ae0: 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e  typedef long lon
2af0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74  g int sqlite_int
2b00: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
2b10: 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67  signed long long
2b20: 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74   int sqlite_uint
2b30: 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64  64;.#endif.typed
2b40: 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  ef sqlite_int64 
2b50: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74  sqlite3_int64;.t
2b60: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69  ypedef sqlite_ui
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e  nt64 sqlite3_uin
2b80: 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63  t64;../*.** If c
2b90: 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70  ompiling for a p
2ba0: 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61  rocessor that la
2bb0: 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  cks floating poi
2bc0: 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73  nt support,.** s
2bd0: 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65  ubstitute intege
2be0: 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70  r for floating-p
2bf0: 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  oint..*/.#ifdef 
2c00: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41  SQLITE_OMIT_FLOA
2c10: 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66  TING_POINT.# def
2c20: 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  ine double sqlit
2c30: 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a  e3_int64.#endif.
2c40: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c50: 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62   Closing A Datab
2c60: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
2c70: 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71  * DESTRUCTOR: sq
2c80: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
2c90: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2ca0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
2cb0: 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73  se_v2() routines
2cc0: 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 73   are destructors
2cd0: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  .** for the [sql
2ce0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  ite3] object..**
2cf0: 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
2d00: 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73  e3_close() and s
2d10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2d20: 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  ) return [SQLITE
2d30: 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b  _OK] if.** the [
2d40: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2d50: 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  is successfully 
2d60: 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c  destroyed and al
2d70: 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  l associated.** 
2d80: 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64 65  resources are de
2d90: 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  allocated..**.**
2da0: 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
2db0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2dc0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2dd0: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2de0: 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2df0: 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  ts or unfinished
2e00: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2e10: 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c  objects then sql
2e20: 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20  ite3_close().** 
2e30: 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64  will leave the d
2e40: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e50: 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75  on open and retu
2e60: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
2e70: 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
2e80: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63  _close_v2() is c
2e90: 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e  alled with unfin
2ea0: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 20  alized prepared 
2eb0: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e  statements.** an
2ec0: 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20  d/or unfinished 
2ed0: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c  sqlite3_backups,
2ee0: 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
2ef0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  se connection be
2f00: 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73  comes.** an unus
2f10: 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68  able "zombie" wh
2f20: 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ich will automat
2f30: 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f  ically be deallo
2f40: 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a  cated when the.*
2f50: 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 20  * last prepared 
2f60: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e  statement is fin
2f70: 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61  alized or the la
2f80: 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  st sqlite3_backu
2f90: 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64  p is.** finished
2fa0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  .  The sqlite3_c
2fb0: 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66  lose_v2() interf
2fc0: 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ace is intended 
2fd0: 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20  for use with.** 
2fe0: 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74  host languages t
2ff0: 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65 20  hat are garbage 
3000: 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77  collected, and w
3010: 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20 69  here the order i
3020: 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72  n which.** destr
3030: 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65  uctors are calle
3040: 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a  d is arbitrary..
3050: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
3060: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
3070: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
3080: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
3090: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
30a0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
30b0: 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73  lob_close | clos
30c0: 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e  e] all [BLOB han
30d0: 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b  dles], and .** [
30e0: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66  sqlite3_backup_f
30f0: 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20  inish | finish] 
3100: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  all [sqlite3_bac
3110: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73  kup] objects ass
3120: 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
3130: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
3140: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74  ject prior to at
3150: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73  tempting to clos
3160: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e  e the object.  ^
3170: 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c  If.** sqlite3_cl
3180: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  ose_v2() is call
3190: 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73  ed on a [databas
31a0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
31b0: 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20  at still has.** 
31c0: 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65  outstanding [pre
31d0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
31e0: 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ], [BLOB handles
31f0: 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71  ], and/or.** [sq
3200: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
3210: 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72 65  jects then it re
3220: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
3230: 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f  ] and the deallo
3240: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73  cation.** of res
3250: 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72 72  ources is deferr
3260: 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72  ed until all [pr
3270: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3280: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3290: 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  s],.** and [sqli
32a0: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
32b0: 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73  cts are also des
32c0: 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  troyed..**.** ^I
32d0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  f an [sqlite3] o
32e0: 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f 79  bject is destroy
32f0: 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73  ed while a trans
3300: 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a  action is open,.
3310: 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ** the transacti
3320: 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  on is automatica
3330: 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  lly rolled back.
3340: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72  .**.** The C par
3350: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
3360: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64  e3_close(C)] and
3370: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
3380: 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  v2(C)].** must b
3390: 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a  e either a NULL.
33a0: 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e  ** pointer or an
33b0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
33c0: 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e  t pointer obtain
33d0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
33e0: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
33f0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
3400: 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
3410: 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
3420: 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63  not previously c
3430: 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69  losed..** ^Calli
3440: 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  ng sqlite3_close
3450: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c  () or sqlite3_cl
3460: 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 20  ose_v2() with a 
3470: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
3480: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61  argument is a ha
3490: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f  rmless no-op..*/
34a0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
34b0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71  sqlite3_close(sq
34c0: 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f  lite3*);.SQLITE_
34d0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
34e0: 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33  close_v2(sqlite3
34f0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
3500: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
3510: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
3520: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
3530: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
3540: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
3550: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
3560: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
3570: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
3580: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
3590: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
35a0: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
35b0: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
35c0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
35d0: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
35e0: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
35f0: 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f  terface.** METHO
3600: 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
3610: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3620: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3630: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3640: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3650: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3660: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3670: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
3680: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3690: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
36a0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
36b0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
36c0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
36d0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
36e0: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
36f0: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
3700: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3710: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
3720: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
3730: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3740: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3750: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3760: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3770: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
3780: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
3790: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
37a0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37b0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
37c0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
37d0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
37e0: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
37f0: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
3800: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3810: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3820: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
3830: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3840: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3850: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3860: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3870: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
3880: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
3890: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
38a0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
38b0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
38c0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
38d0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
38e0: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
38f0: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3900: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3910: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3920: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3930: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3940: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3950: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3960: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3970: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
3980: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
3990: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
39a0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
39b0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
39c0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
39d0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
39e0: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
39f0: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3a00: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3a10: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3a20: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3a30: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3a40: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3a50: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3a60: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3a70: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
3a80: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
3a90: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
3aa0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
3ab0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
3ac0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3ad0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3ae0: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3af0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3b00: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3b10: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3b20: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3b30: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3b40: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3b50: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3b60: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61  sqlite3_exec() a
3b70: 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d  fter the error m
3b80: 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
3b90: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
3ba0: 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74  d..** ^If the 5t
3bb0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3bc0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3bd0: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f   not NULL and no
3be0: 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72   errors.** occur
3bf0: 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65  , then sqlite3_e
3c00: 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70  xec() sets the p
3c10: 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74  ointer in its 5t
3c20: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
3c30: 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65  * NULL before re
3c40: 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  turning..**.** ^
3c50: 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78  If an sqlite3_ex
3c60: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65  ec() callback re
3c70: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
3c80: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3c90: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
3ca0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f  turns SQLITE_ABO
3cb0: 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b  RT without invok
3cc0: 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ing the callback
3cd0: 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69   again and.** wi
3ce0: 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e  thout running an
3cf0: 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c  y subsequent SQL
3d00: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
3d10: 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75  ** ^The 2nd argu
3d20: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
3d30: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3d40: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ack function is 
3d50: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
3d60: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
3d70: 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72  result.  ^The 3r
3d80: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3d90: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3da0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
3db0: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
3dc0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
3dd0: 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66  obtained as if f
3de0: 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
3df0: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
3e00: 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c  one for each col
3e10: 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65  umn.  ^If an ele
3e20: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73  ment of a.** res
3e30: 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20  ult row is NULL 
3e40: 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  then the corresp
3e50: 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f  onding string po
3e60: 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a  inter for the.**
3e70: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3e80: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55  callback is a NU
3e90: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
3ea0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3eb0: 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  o the.** sqlite3
3ec0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3ed0: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
3ee0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
3ef0: 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a  ngs where each.*
3f00: 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e  * entry represen
3f10: 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63  ts the name of c
3f20: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73  orresponding res
3f30: 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62  ult column as ob
3f40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3f50: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
3f60: 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ame()]..**.** ^I
3f70: 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
3f80: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3f90: 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  xec() is a NULL 
3fa0: 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74  pointer, a point
3fb0: 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74  er.** to an empt
3fc0: 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70  y string, or a p
3fd0: 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74  ointer that cont
3fe0: 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73  ains only whites
3ff0: 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20  pace and/or .** 
4000: 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68  SQL comments, th
4010: 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d  en no SQL statem
4020: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74  ents are evaluat
4030: 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  ed and the datab
4040: 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ase.** is not ch
4050: 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73  anged..**.** Res
4060: 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a  trictions:.**.**
4070: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
4080: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
4090: 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  st ensure that t
40a0: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
40b0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
40c0: 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20  ().**      is a 
40d0: 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b  valid and open [
40e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
40f0: 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ion]..** <li> Th
4100: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
4110: 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
4120: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
4130: 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
4140: 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20   by.**      the 
4150: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
4160: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4170: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
4180: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
4190: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
41a0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
41b0: 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c  t modify the SQL
41c0: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
41d0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20  passed into.**  
41e0: 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61      the 2nd para
41f0: 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
4200: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
4210: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
4220: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c  running..** </ul
4230: 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  >.*/.SQLITE_API 
4240: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
4250: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
4260: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4270: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4280: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
4290: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
42a0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42c0: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
42d0: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
42e0: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
42f0: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
4300: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
4310: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
4320: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
4330: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4340: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4350: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
4360: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
4370: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
4380: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4390: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
43a0: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
43b0: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
43c0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
43d0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
43e0: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
43f0: 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a  de definitions}.
4400: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
4410: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
4420: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
4430: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
4440: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
4450: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
4460: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73   indicate succes
4470: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
4480: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f  .** New error co
4490: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  des may be added
44a0: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
44b0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
44c0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
44d0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
44e0: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  code definitions
44f0: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ].*/.#define SQL
4500: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
4510: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4520: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
4530: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
4540: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
4550: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
4560: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
4570: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
4580: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4590: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
45a0: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
45b0: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
45c0: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
45d0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
45e0: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
45f0: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
4600: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
4610: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4620: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
4630: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
4640: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
4650: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
4660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
4670: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
4680: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4690: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
46a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
46b0: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
46c0: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
46d0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
46e0: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
46f0: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
4700: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
4710: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4720: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4730: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
4740: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
4750: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
4760: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4770: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
4780: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4790: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
47a0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
47b0: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
47c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
47d0: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
47e0: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
47f0: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
4800: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
4810: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4820: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
4830: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
4840: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
4850: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4860: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
4870: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
4880: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4890: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48b0: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
48c0: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
48d0: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
48e0: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
48f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4900: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
4910: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4920: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4930: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4940: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
4950: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
4960: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
4970: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
4980: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4990: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
49a0: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
49b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
49c0: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
49d0: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
49e0: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
49f0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4a00: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
4a10: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4a20: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
4a30: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
4a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
4a50: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
4a60: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
4a70: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
4a80: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4a90: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4aa0: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4ab0: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4ad0: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4ae0: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4af0: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
4b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
4b10: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4b20: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4b30: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4b40: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
4b50: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4b60: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4b70: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4b80: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4b90: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4ba0: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4bb0: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4bc0: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4bd0: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4be0: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4bf0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4c00: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4c10: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4c20: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4c30: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4c40: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4c50: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4c60: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4c70: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20  e SQLITE_NOTICE 
4c80: 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74       27   /* Not
4c90: 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20  ifications from 
4ca0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4cb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4cc0: 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20  WARNING     28  
4cd0: 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f   /* Warnings fro
4ce0: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
4cf0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4d00: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
4d10: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
4d20: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
4d30: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
4d50: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
4d60: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4d70: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
4d80: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
4d90: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4da0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
4db0: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
4dc0: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
4dd0: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
4de0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66   result code def
4df0: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  initions}.**.** 
4e00: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4e10: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4e20: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4e30: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4e40: 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72  30 integer.** [r
4e50: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48  esult codes].  H
4e60: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e  owever, experien
4e70: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61  ce has shown tha
4e80: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65  t many of.** the
4e90: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  se result codes 
4ea0: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67  are too coarse-g
4eb0: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f  rained.  They do
4ec0: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a   not provide as.
4ed0: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74  ** much informat
4ee0: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65  ion about proble
4ef0: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72  ms as programmer
4f00: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49  s might like.  I
4f10: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a  n an effort to.*
4f20: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20  * address this, 
4f30: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
4f40: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f  f SQLite (versio
4f50: 6e 20 33 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a  n 3.3.8 [dateof:
4f60: 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61  3.3.8].** and la
4f70: 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20  ter) include.** 
4f80: 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69  support for addi
4f90: 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f  tional result co
4fa0: 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65  des that provide
4fb0: 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69   more detailed i
4fc0: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
4fd0: 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73  out errors. Thes
4fe0: 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  e [extended resu
4ff0: 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e  lt codes] are en
5000: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
5010: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
5020: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
5030: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
5040: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
5050: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
5060: 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c  des()] API.  Or,
5070: 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f   the extended co
5080: 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f  de for.** the mo
5090: 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20  st recent error 
50a0: 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
50b0: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
50c0: 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
50d0: 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  de()]..*/.#defin
50e0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
50f0: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
5100: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5110: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5120: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5130: 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20  ORT_READ        
5140: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5150: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5160: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49  SQLITE_IOERR_WRI
5170: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  TE             (
5180: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5190: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
51a0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e  QLITE_IOERR_FSYN
51b0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  C             (S
51c0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34  QLITE_IOERR | (4
51d0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51e0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46  LITE_IOERR_DIR_F
51f0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51  SYNC         (SQ
5200: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c  LITE_IOERR | (5<
5210: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5220: 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41  ITE_IOERR_TRUNCA
5230: 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TE          (SQL
5240: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c  ITE_IOERR | (6<<
5250: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5260: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20  TE_IOERR_FSTAT  
5270: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5280: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38  TE_IOERR | (7<<8
5290: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
52a0: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20  E_IOERR_UNLOCK  
52b0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
52c0: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29  E_IOERR | (8<<8)
52d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52e0: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20  _IOERR_RDLOCK   
52f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5300: 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29  _IOERR | (9<<8))
5310: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5320: 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20  IOERR_DELETE    
5330: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5340: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29  IOERR | (10<<8))
5350: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5360: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20  IOERR_BLOCKED   
5370: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5380: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29  IOERR | (11<<8))
5390: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53a0: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20  IOERR_NOMEM     
53b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
53c0: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29  IOERR | (12<<8))
53d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53e0: 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20  IOERR_ACCESS    
53f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5400: 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29  IOERR | (13<<8))
5410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5420: 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52  IOERR_CHECKRESER
5430: 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f  VEDLOCK (SQLITE_
5440: 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29  IOERR | (14<<8))
5450: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5460: 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20  IOERR_LOCK      
5470: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5480: 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29  IOERR | (15<<8))
5490: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54a0: 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20  IOERR_CLOSE     
54b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
54c0: 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29  IOERR | (16<<8))
54d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54e0: 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20  IOERR_DIR_CLOSE 
54f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5500: 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29  IOERR | (17<<8))
5510: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5520: 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20  IOERR_SHMOPEN   
5530: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5540: 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29  IOERR | (18<<8))
5550: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5560: 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20  IOERR_SHMSIZE   
5570: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5580: 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29  IOERR | (19<<8))
5590: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55a0: 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20  IOERR_SHMLOCK   
55b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
55c0: 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29  IOERR | (20<<8))
55d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55e0: 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20  IOERR_SHMMAP    
55f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5600: 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29  IOERR | (21<<8))
5610: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5620: 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20  IOERR_SEEK      
5630: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5640: 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29  IOERR | (22<<8))
5650: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5660: 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45  IOERR_DELETE_NOE
5670: 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  NT      (SQLITE_
5680: 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29  IOERR | (23<<8))
5690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56a0: 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20  IOERR_MMAP      
56b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56c0: 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29  IOERR | (24<<8))
56d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56e0: 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54  IOERR_GETTEMPPAT
56f0: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
5700: 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29  IOERR | (25<<8))
5710: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5720: 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20  IOERR_CONVPATH  
5730: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5740: 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29  IOERR | (26<<8))
5750: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5760: 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20 20  IOERR_VNODE     
5770: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5780: 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29 29  IOERR | (27<<8))
5790: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
57a0: 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20 20 20  IOERR_AUTH      
57b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
57c0: 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 29 29  IOERR | (28<<8))
57d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
57e0: 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43  LOCKED_SHAREDCAC
57f0: 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  HE      (SQLITE_
5800: 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29  LOCKED |  (1<<8)
5810: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5820: 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20  _BUSY_RECOVERY  
5830: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5840: 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38  _BUSY   |  (1<<8
5850: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5860: 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20  E_BUSY_SNAPSHOT 
5870: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5880: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c  E_BUSY   |  (2<<
5890: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58a0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45  TE_CANTOPEN_NOTE
58b0: 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49  MPDIR      (SQLI
58c0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31  TE_CANTOPEN | (1
58d0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
58e0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53  LITE_CANTOPEN_IS
58f0: 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51  DIR          (SQ
5900: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5910: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5920: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
5930: 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28  FULLPATH       (
5940: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5950: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5960: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5970: 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20  N_CONVPATH      
5980: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5990: 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  N | (4<<8)).#def
59a0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
59b0: 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  PT_VTAB         
59c0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55     (SQLITE_CORRU
59d0: 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  PT | (1<<8)).#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
59f0: 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20  ONLY_RECOVERY   
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5a10: 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23  ONLY | (1<<8)).#
5a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
5a30: 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20  ADONLY_CANTLOCK 
5a40: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5a50: 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29  ADONLY | (2<<8))
5a60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a70: 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43  READONLY_ROLLBAC
5a80: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
5a90: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38  READONLY | (3<<8
5aa0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5ab0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56  E_READONLY_DBMOV
5ac0: 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ED        (SQLIT
5ad0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c  E_READONLY | (4<
5ae0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5af0: 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41  ITE_ABORT_ROLLBA
5b00: 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  CK          (SQL
5b10: 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c  ITE_ABORT | (2<<
5b20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b30: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48  TE_CONSTRAINT_CH
5b40: 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49  ECK        (SQLI
5b50: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b60: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5b70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b80: 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28  T_COMMITHOOK   (
5b90: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5ba0: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
5bb0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5bc0: 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59  RAINT_FOREIGNKEY
5bd0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5be0: 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a  RAINT | (3<<8)).
5bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5c00: 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49  ONSTRAINT_FUNCTI
5c10: 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  ON     (SQLITE_C
5c20: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c  ONSTRAINT | (4<<
5c30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c40: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f  TE_CONSTRAINT_NO
5c50: 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49  TNULL      (SQLI
5c60: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5c70: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
5c80: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c90: 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28  T_PRIMARYKEY   (
5ca0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5cb0: 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  T | (6<<8)).#def
5cc0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5cd0: 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20  RAINT_TRIGGER   
5ce0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5cf0: 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a  RAINT | (7<<8)).
5d00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5d10: 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45  ONSTRAINT_UNIQUE
5d20: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5d30: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c  ONSTRAINT | (8<<
5d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d50: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54  TE_CONSTRAINT_VT
5d60: 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  AB         (SQLI
5d70: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5d80: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5d90: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5da0: 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28  T_ROWID        (
5db0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5dc0: 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66  T |(10<<8)).#def
5dd0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
5de0: 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20  E_RECOVER_WAL   
5df0: 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43     (SQLITE_NOTIC
5e00: 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  E | (1<<8)).#def
5e10: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
5e20: 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41  E_RECOVER_ROLLBA
5e30: 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43  CK (SQLITE_NOTIC
5e40: 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  E | (2<<8)).#def
5e50: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
5e60: 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20  NG_AUTOINDEX    
5e70: 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49     (SQLITE_WARNI
5e80: 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NG | (1<<8)).#de
5e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
5ea0: 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20  _USER           
5eb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48      (SQLITE_AUTH
5ec0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5ed0: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41  ne SQLITE_OK_LOA
5ee0: 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20  D_PERMANENTLY   
5ef0: 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28    (SQLITE_OK | (
5f00: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  1<<8))../*.** CA
5f10: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
5f20: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
5f30: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
5f40: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
5f50: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
5f60: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
5f70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5f80: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
5f90: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
5fa0: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
5fb0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
5fc0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
5fd0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
5fe0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5ff0: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
6000: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6010: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
6020: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6030: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6040: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
6050: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6060: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
6070: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6080: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6090: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
60a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
60b0: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
60c0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
60d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60e0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
60f0: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
6100: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
6110: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6120: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
6130: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
6140: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6150: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6160: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
6170: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
6180: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6190: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61a0: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
61b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
61c0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
61d0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
61e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61f0: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20  _OPEN_MEMORY    
6200: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
6210: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6220: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6230: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6240: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
6250: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6260: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6270: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6280: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
6290: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
62a0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
62b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62c0: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
62d0: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
62e0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
62f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6300: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
6310: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
6320: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6330: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6340: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
6350: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
6360: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6370: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6380: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
6390: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
63a0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
63b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
63c0: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
63d0: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
63e0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
63f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6400: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
6410: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
6420: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6430: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6440: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6450: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
6460: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
6470: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6480: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
64a0: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
64b0: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
64c0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
64d0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
64e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
64f0: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
6500: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
6510: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6520: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6530: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6540: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
6550: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
6560: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6570: 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20  /../* Reserved: 
6580: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6590: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30          0x00F000
65a0: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00 */../*.** CAP
65b0: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
65c0: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a  aracteristics.**
65d0: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
65e0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
65f0: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
6600: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6610: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
6620: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
6630: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
6640: 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74   of these.** bit
6650: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69   values expressi
6660: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72  ng I/O character
6670: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61  istics of the ma
6680: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65  ss storage.** de
6690: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20  vice that holds 
66a0: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68  the file that th
66b0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
66c0: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73  thods].** refers
66d0: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53   to..**.** The S
66e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
66f0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
6700: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
6710: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
6720: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6730: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6740: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
6750: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
6760: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
6770: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
6780: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
6790: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
67a0: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
67b0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
67c0: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
67d0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
67e0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
67f0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
6800: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
6810: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
6820: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
6830: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
6840: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
6850: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
6860: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
6870: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
6880: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
6890: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
68a0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
68b0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
68c0: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
68d0: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
68e0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
68f0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
6900: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
6910: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6920: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6930: 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79  ERWRITE property
6940: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61   means that.** a
6950: 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c  fter reboot foll
6960: 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72  owing a crash or
6970: 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65   power loss, the
6980: 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61   only bytes in a
6990: 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65  .** file that we
69a0: 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68  re written at th
69b0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65  e application le
69c0: 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63  vel might have c
69d0: 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68  hanged.** and th
69e0: 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65  at adjacent byte
69f0: 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69  s, even bytes wi
6a00: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65  thin the same se
6a10: 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72  ctor are.** guar
6a20: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63  anteed to be unc
6a30: 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c  hanged.  The SQL
6a40: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6a50: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a  TABLE_WHEN_OPEN.
6a60: 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65  ** flag indicate
6a70: 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61  s that a file ca
6a80: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20  nnot be deleted 
6a90: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a  when open.  The.
6aa0: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ** SQLITE_IOCAP_
6ab0: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69  IMMUTABLE flag i
6ac0: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
6ad0: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20  e file is on.** 
6ae0: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20  read-only media 
6af0: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  and cannot be ch
6b00: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72  anged even by pr
6b10: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20  ocesses with.** 
6b20: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65  elevated privile
6b30: 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ges..*/.#define 
6b40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6b50: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
6b60: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
6b70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6b80: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
6b90: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6ba0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
6bb0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6bc0: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
6bd0: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
6be0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6bf0: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
6c00: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6c10: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
6c20: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
6c30: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6c40: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
6c50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6c60: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
6c70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
6c80: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6c90: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6ca0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6cb0: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
6cc0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6cd0: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
6ce0: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
6cf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6d00: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
6d10: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6d20: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
6d30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6d40: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
6d50: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
6d60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6d70: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
6d80: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6d90: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
6da0: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6db0: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
6dc0: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
6dd0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6de0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
6df0: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30  RITE    0x000010
6e00: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6e10: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
6e20: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  E              0
6e30: 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00002000../*.**
6e40: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
6e50: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
6e60: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
6e70: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
6e80: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6e90: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
6ea0: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
6eb0: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
6ec0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
6ed0: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
6ee0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6ef0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6f00: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
6f10: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
6f20: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
6f30: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
6f40: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
6f50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6f60: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
6f70: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
6f80: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
6f90: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
6fa0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6fb0: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
6fc0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
6fd0: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
6fe0: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
6ff0: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
7000: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
7010: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
7020: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7030: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
7040: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
7050: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
7060: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
7070: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
7080: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
7090: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
70a0: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
70b0: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
70c0: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
70d0: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
70e0: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
70f0: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
7100: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
7110: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
7120: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
7130: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
7140: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
7150: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
7160: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
7170: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
7180: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
7190: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
71a0: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
71b0: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
71c0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
71d0: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
71e0: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
71f0: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
7200: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
7210: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
7220: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
7230: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
7240: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
7250: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
7260: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
7270: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
7280: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
7290: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
72a0: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
72b0: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
72c0: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
72d0: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
72e0: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
72f0: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
7300: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
7310: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
7320: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
7330: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
7340: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
7350: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
7360: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
7370: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
7380: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
7390: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
73a0: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
73b0: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
73c0: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
73d0: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
73e0: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
73f0: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
7400: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
7410: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
7420: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
7430: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
7440: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
7450: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
7460: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
7470: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
7480: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
7490: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
74a0: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
74b0: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
74c0: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
74d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
74e0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
74f0: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
7500: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7510: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
7520: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
7530: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
7540: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
7550: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7560: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
7570: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
7580: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
7590: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
75a0: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
75b0: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
75c0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
75d0: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
75e0: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
75f0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
7600: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7610: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
7620: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
7630: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
7640: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
7650: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
7660: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
7670: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
7680: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
7690: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
76a0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
76b0: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
76c0: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
76d0: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
76e0: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
76f0: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
7700: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7710: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
7720: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
7730: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
7740: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
7750: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
7760: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
7770: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
7780: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
7790: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
77a0: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
77b0: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
77c0: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
77d0: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
77e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
77f0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
7800: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
7810: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7820: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
7830: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
7840: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
7850: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7860: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
7870: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
7880: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
7890: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
78a0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
78b0: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
78c0: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
78d0: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
78e0: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
78f0: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
7900: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
7910: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
7920: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
7930: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
7940: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
7950: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
7960: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
7970: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
7980: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
7990: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
79a0: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
79b0: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
79c0: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
79d0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
79e0: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
79f0: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
7a00: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
7a10: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
7a20: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
7a30: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
7a40: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
7a50: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
7a60: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7a70: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
7a80: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7a90: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
7aa0: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
7ab0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7ac0: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
7ad0: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
7ae0: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
7af0: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
7b00: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
7b10: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
7b20: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
7b30: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
7b40: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
7b50: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
7b60: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
7b70: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
7b80: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
7b90: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
7ba0: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
7bb0: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
7bc0: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
7bd0: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
7be0: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
7bf0: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
7c00: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
7c10: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
7c20: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
7c30: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7c40: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
7c50: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
7c60: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
7c70: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
7c80: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
7c90: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7ca0: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
7cb0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
7cc0: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
7cd0: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
7ce0: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
7cf0: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
7d00: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
7d10: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
7d20: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
7d30: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
7d40: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
7d50: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
7d60: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
7d70: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
7d80: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
7d90: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
7da0: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
7db0: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
7dc0: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
7dd0: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
7de0: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
7df0: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
7e00: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
7e10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
7e20: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
7e30: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
7e40: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
7e50: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
7e60: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7e70: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
7e80: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
7e90: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
7ea0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
7eb0: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
7ec0: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
7ed0: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
7ee0: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
7ef0: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
7f00: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
7f10: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
7f20: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
7f30: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
7f40: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
7f50: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
7f60: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
7f70: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
7f80: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
7f90: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
7fa0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7fb0: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
7fc0: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
7fd0: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
7fe0: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
7ff0: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
8000: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
8010: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
8020: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
8030: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
8040: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
8050: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
8060: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
8070: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
8080: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
8090: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
80a0: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
80b0: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
80c0: 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f  * A [file contro
80d0: 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74  l opcodes | list
80e0: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
80f0: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
8100: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
8110: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
8120: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
8130: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
8140: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
8150: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
8160: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
8170: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
8180: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
8190: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
81a0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
81b0: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
81c0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
81d0: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
81e0: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
81f0: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
8200: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
8210: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
8220: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
8230: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
8240: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
8250: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
8260: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
8270: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
8280: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
8290: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
82a0: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
82b0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
82c0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
82d0: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
82e0: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
82f0: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
8300: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
8310: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
8320: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
8330: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
8340: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8350: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
8360: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8370: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
8380: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8390: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
83a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
83b0: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
83c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
83d0: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
83e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
83f0: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
8400: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8410: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
8420: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8430: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
8440: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8450: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
8460: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
8470: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
8480: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8490: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
84a0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
84b0: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57  AP_UNDELETABLE_W
84c0: 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69  HEN_OPEN].** <li
84d0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
84e0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
84f0: 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ITE].** <li> [SQ
8500: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
8510: 41 42 4c 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ABLE].** </ul>.*
8520: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
8530: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
8540: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8550: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
8560: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
8570: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
8580: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
8590: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
85a0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
85b0: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
85c0: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
85d0: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
85e0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
85f0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
8600: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
8610: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
8620: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
8630: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
8640: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
8650: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
8660: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
8670: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
8680: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
8690: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
86a0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
86b0: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
86c0: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
86d0: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
86e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
86f0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
8700: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
8710: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
8720: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
8730: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
8740: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
8750: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
8760: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
8770: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
8780: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
8790: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
87a0: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
87b0: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
87c0: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
87d0: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
87e0: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
87f0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8800: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
8810: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
8820: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
8830: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8840: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
8850: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
8860: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
8870: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
8880: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8890: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
88a0: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
88b0: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
88c0: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
88d0: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
88e0: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
88f0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8900: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
8910: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
8920: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
8930: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
8940: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
8950: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
8960: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
8970: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8980: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8990: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
89a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
89b0: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
89c0: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
89d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
89e0: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
89f0: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
8a00: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8a10: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
8a20: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
8a30: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8a40: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
8a50: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
8a60: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
8a70: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
8a80: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
8a90: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
8aa0: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
8ab0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
8ac0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8ad0: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
8ae0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
8af0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
8b00: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
8b10: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8b20: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
8b30: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  le*);.  /* Metho
8b40: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8b50: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31  id for version 1
8b60: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
8b70: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  Map)(sqlite3_fil
8b80: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74  e*, int iPg, int
8b90: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64   pgsz, int, void
8ba0: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20   volatile**);.  
8bb0: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28  int (*xShmLock)(
8bc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8bd0: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e  nt offset, int n
8be0: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8bf0: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69  void (*xShmBarri
8c00: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  er)(sqlite3_file
8c10: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8c20: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  Unmap)(sqlite3_f
8c30: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65  ile*, int delete
8c40: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  Flag);.  /* Meth
8c50: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8c60: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8c70: 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65  2 */.  int (*xFe
8c80: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
8c90: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8ca0: 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d  4 iOfst, int iAm
8cb0: 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20  t, void **pp);. 
8cc0: 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29   int (*xUnfetch)
8cd0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8ce0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
8cf0: 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20  fst, void *p);. 
8d00: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8d10: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8d20: 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f  version 3 */.  /
8d30: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
8d40: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
8d50: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
8d60: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
8d70: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
8d80: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
8d90: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59  l Opcodes.** KEY
8da0: 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e  WORDS: {file con
8db0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66  trol opcodes} {f
8dc0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
8dd0: 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  de}.**.** These 
8de0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
8df0: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
8e00: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
8e10: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
8e20: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
8e30: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
8e40: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
8e50: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8e60: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
8e70: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e..**.** <ul>.**
8e80: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8e90: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a  NTL_LOCKSTATE]].
8ea0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8eb0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
8ec0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
8ed0: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
8ee0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
8ef0: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
8f00: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
8f10: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
8f20: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
8f30: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
8f40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
8f50: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
8f60: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
8f70: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
8f80: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
8f90: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
8fa0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
8fb0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
8fc0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
8fd0: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
8fe0: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
8ff0: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
9000: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
9010: 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c  sting and is onl
9020: 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e  y available when
9030: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54   the SQLITE_TEST
9040: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
9050: 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
9060: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9070: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
9080: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  INT]].** The [SQ
9090: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
90a0: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20  HINT] opcode is 
90b0: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74  used by SQLite t
90c0: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a  o give the VFS.*
90d0: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f  * layer a hint o
90e0: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20  f how large the 
90f0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
9100: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75  ll grow to be du
9110: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72  ring the.** curr
9120: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  ent transaction.
9130: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e    This hint is n
9140: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ot guaranteed to
9150: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74   be accurate but
9160: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20   it.** is often 
9170: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65  close.  The unde
9180: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74  rlying VFS might
9190: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c   choose to preal
91a0: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a  locate database.
91b0: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61  ** file space ba
91c0: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  sed on this hint
91d0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c   in order to hel
91e0: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20  p writes to the 
91f0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
9200: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a   run faster..**.
9210: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9220: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
9230: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9240: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
9250: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ZE] opcode is us
9260: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68  ed to request th
9270: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78  at the VFS.** ex
9280: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61  tends and trunca
9290: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  tes the database
92a0: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20   file in chunks 
92b0: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66  of a size specif
92c0: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73  ied.** by the us
92d0: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61  er. The fourth a
92e0: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
92f0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9300: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70  ()] should .** p
9310: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67  oint to an integ
9320: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f  er (type int) co
9330: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77  ntaining the new
9340: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75   chunk-size to u
9350: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f  se.** for the no
9360: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65  minated database
9370: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74  . Allocating dat
9380: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65  abase file space
9390: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75   in large.** chu
93a0: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20  nks (say 1MB at 
93b0: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64  a time), may red
93c0: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20  uce file-system 
93d0: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  fragmentation an
93e0: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72  d.** improve per
93f0: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65  formance on some
9400: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20   systems..**.** 
9410: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9420: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
9430: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9440: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9450: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TER] opcode is u
9460: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20  sed to obtain a 
9470: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
9480: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
9490: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74   object associat
94a0: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ed with a partic
94b0: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
94c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
94d0: 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46  e also [SQLITE_F
94e0: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
94f0: 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  NTER]..**.** <li
9500: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9510: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
9520: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9530: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
9540: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
9550: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
9560: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
9570: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
9580: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
9590: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a  iated with the j
95a0: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74  ournal file (eit
95b0: 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c  her.** the [roll
95c0: 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72  back journal] or
95d0: 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61   the [write-ahea
95e0: 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61  d log]) for a pa
95f0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
9600: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
9610: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49    See also [SQLI
9620: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9630: 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  INTER]..**.** <l
9640: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9650: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
9660: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20  ** No longer in 
9670: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  use..**.** <li>[
9680: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9690: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NC]].** The [SQL
96a0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20  ITE_FCNTL_SYNC] 
96b0: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
96c0: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
96d0: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20  y SQLite and.** 
96e0: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
96f0: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
9700: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  re the xSync met
9710: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hod is invoked o
9720: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  n a.** database 
9730: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e  file descriptor.
9740: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e   Or, if the xSyn
9750: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20  c method is not 
9760: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61  invoked .** beca
9770: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73  use the user has
9780: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69   configured SQLi
9790: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41  te with .** [PRA
97a0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20  GMA synchronous 
97b0: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f  | PRAGMA synchro
97c0: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20  nous=OFF] it is 
97d0: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65  invoked in place
97e0: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e   .** of the xSyn
97f0: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73  c method. In mos
9800: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69  t cases, the poi
9810: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61  nter argument pa
9820: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69  ssed with.** thi
9830: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
9840: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c  s NULL. However,
9850: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
9860: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73   file is being s
9870: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  ynced.** as part
9880: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61   of a multi-data
9890: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65  base commit, the
98a0: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
98b0: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   to a nul-termin
98c0: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63  ated.** string c
98d0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72  ontaining the tr
98e0: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65  ansactions maste
98f0: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e  r-journal file n
9900: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20  ame. VFSes that 
9910: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  .** do not need 
9920: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75  this signal shou
9930: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
9940: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
9950: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a  Applications .**
9960: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
9970: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9980: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
9990: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
99a0: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64  ing so may .** d
99b0: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
99c0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
99d0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
99e0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
99f0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
9a00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
9a10: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a  MIT_PHASETWO]].*
9a20: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9a30: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
9a40: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TWO] opcode is g
9a50: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
9a60: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  lly by SQLite.**
9a70: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65   and sent to the
9a80: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61   VFS after a tra
9a90: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65  nsaction has bee
9aa0: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65  n committed imme
9ab0: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62  diately.** but b
9ac0: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61  efore the databa
9ad0: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20  se is unlocked. 
9ae0: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  VFSes that do no
9af0: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9b00: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c  al.** should sil
9b10: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9b20: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9b30: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9b40: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
9b50: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9b60: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
9b70: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
9b80: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
9b90: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  .** operation of
9ba0: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9bb0: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
9bc0: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
9bd0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9be0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
9bf0: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
9c00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9c10: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
9c20: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
9c30: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
9c40: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
9c50: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
9c60: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
9c70: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
9c80: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
9c90: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
9ca0: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
9cb0: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
9cc0: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
9cd0: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
9ce0: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
9cf0: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
9d00: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
9d10: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
9d20: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
9d30: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
9d40: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
9d50: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
9d60: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
9d70: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
9d80: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
9d90: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
9da0: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
9db0: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
9dc0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
9dd0: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
9de0: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
9df0: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
9e00: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
9e10: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
9e20: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9e30: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
9e40: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
9e50: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
9e60: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
9e70: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
9e80: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
9e90: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
9ea0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
9eb0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9ec0: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
9ed0: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
9ee0: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
9ef0: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
9f00: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
9f10: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
9f20: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
9f30: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
9f40: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
9f50: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
9f60: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
9f70: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
9f80: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
9f90: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
9fa0: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
9fb0: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
9fc0: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
9fd0: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
9fe0: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
9ff0: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
a000: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
a010: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
a020: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a030: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
a040: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
a050: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
a060: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
a070: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a080: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a090: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
a0a0: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
a0b0: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
a0c0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
a0d0: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
a0e0: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
a0f0: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
a100: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
a110: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
a120: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
a130: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
a140: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
a150: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
a160: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
a170: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
a180: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
a190: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
a1a0: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
a1b0: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
a1c0: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
a1d0: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
a1e0: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
a1f0: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
a200: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
a210: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
a220: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
a230: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
a240: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
a250: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
a260: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
a270: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
a280: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
a290: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
a2a0: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
a2b0: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
a2c0: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
a2d0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
a2e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a2f0: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
a300: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
a310: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
a320: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
a330: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
a340: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
a350: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
a360: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
a370: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
a380: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a390: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a3a0: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a3b0: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a3c0: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
a3d0: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
a3e0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a3f0: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
a400: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
a410: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
a420: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
a430: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
a440: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
a450: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
a460: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
a470: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
a480: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
a490: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
a4a0: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
a4b0: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
a4c0: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
a4d0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
a4e0: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
a4f0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
a500: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
a510: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a520: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a530: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a540: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a550: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a560: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a570: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a580: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a590: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
a5a0: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a5b0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
a5c0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a5d0: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a5e0: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a5f0: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a600: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
a610: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
a620: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a630: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a640: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
a650: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
a660: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
a670: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
a680: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
a690: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
a6a0: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
a6b0: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
a6c0: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
a6d0: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
a6e0: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
a6f0: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
a700: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
a710: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
a720: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
a730: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
a740: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
a750: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
a760: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a770: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
a780: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a790: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
a7a0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
a7b0: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
a7c0: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
a7d0: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
a7e0: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
a7f0: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
a800: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
a810: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
a820: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
a830: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
a840: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
a850: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
a860: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
a870: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
a880: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a890: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
a8a0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a8b0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
a8c0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
a8d0: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
a8e0: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
a8f0: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
a900: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
a910: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
a920: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
a930: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
a940: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
a950: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
a960: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
a970: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
a980: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
a990: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
a9a0: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
a9b0: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
a9c0: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
a9d0: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
a9e0: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
a9f0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
aa00: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
aa10: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
aa20: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
aa30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
aa40: 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  FS_POINTER]].** 
aa50: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
aa60: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20  TL_VFS_POINTER] 
aa70: 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70  opcode finds a p
aa80: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f  ointer to the to
aa90: 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65  p-level.** [VFSe
aaa0: 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20  s] currently in 
aab0: 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75  use.  ^(The argu
aac0: 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c  ment X in.** sql
aad0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
aae0: 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54  l(db,SQLITE_FCNT
aaf0: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29  L_VFS_POINTER,X)
ab00: 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74   must be.** of t
ab10: 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66  ype "[sqlite3_vf
ab20: 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70  s] **".  This op
ab30: 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a  codes will set *
ab40: 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65  X.** to a pointe
ab50: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
ab60: 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68  el VFS.)^.** ^Wh
ab70: 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c  en there are mul
ab80: 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20  tiple VFS shims 
ab90: 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68  in the stack, th
aba0: 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20  is opcode finds 
abb0: 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73  the.** upper-mos
abc0: 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a  t shim only..**.
abd0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
abe0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a  FCNTL_PRAGMA]].*
abf0: 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50  * ^Whenever a [P
ac00: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
ac10: 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b   is parsed, an [
ac20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ac30: 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f  GMA] .** file co
ac40: 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f  ntrol is sent to
ac50: 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74   the open [sqlit
ac60: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
ac70: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
ac80: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
ac90: 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74   file to which t
aca0: 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  he pragma statem
acb0: 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65  ent refers. ^The
acc0: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
acd0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
ace0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
acf0: 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72  ontrol is an arr
ad00: 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72  ay of.** pointer
ad10: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68  s to strings (ch
ad20: 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74  ar**) in which t
ad30: 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e  he second elemen
ad40: 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a  t of the array.*
ad50: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
ad60: 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20   the pragma and 
ad70: 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e  the third elemen
ad80: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
ad90: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67  t to the.** prag
ada0: 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  ma or NULL if th
adb0: 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20  e pragma has no 
adc0: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20  argument.  ^The 
add0: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a  handler for an.*
ade0: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
adf0: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
ae00: 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61  trol can optiona
ae10: 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72  lly make the fir
ae20: 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66  st element.** of
ae30: 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75   the char** argu
ae40: 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20  ment point to a 
ae50: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
ae60: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
ae70: 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74  rintf()].** or t
ae80: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  he equivalent an
ae90: 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69  d that string wi
aea0: 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65  ll become the re
aeb0: 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67  sult of the prag
aec0: 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72  ma or.** the err
aed0: 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68  or message if th
aee0: 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20  e pragma fails. 
aef0: 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
af00: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
af10: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
af20: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f  turns [SQLITE_NO
af30: 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f  TFOUND], then no
af40: 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  rmal .** [PRAGMA
af50: 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e  ] processing con
af60: 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65  tinues.  ^If the
af70: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
af80: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
af90: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
afa0: 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e  SQLITE_OK], then
afb0: 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75   the parser assu
afc0: 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
afd0: 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20  VFS has handled 
afe0: 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c  the PRAGMA itsel
aff0: 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72  f and the parser
b000: 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d   generates a no-
b010: 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  op.** prepared s
b020: 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75  tatement if resu
b030: 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c  lt string is NUL
b040: 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72  L, or that retur
b050: 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  ns a copy.** of 
b060: 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e  the result strin
b070: 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  g if the string 
b080: 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20  is non-NULL..** 
b090: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
b0a0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
b0b0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
b0c0: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74  ns.** any result
b0d0: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e   code other than
b0e0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
b0f0: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
b100: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  ], that means.**
b110: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e   that the VFS en
b120: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72  countered an err
b130: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e  or while handlin
b140: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61  g the [PRAGMA] a
b150: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  nd the.** compil
b160: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41  ation of the PRA
b170: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61  GMA fails with a
b180: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b  n error.  ^The [
b190: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b1a0: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
b1b0: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74  trol occurs at t
b1c0: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
b1d0: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
b1e0: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f   analysis and so
b1f0: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74  .** it is able t
b200: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74  o override built
b210: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  -in [PRAGMA] sta
b220: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c  tements..**.** <
b230: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b240: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a  L_BUSYHANDLER]].
b250: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
b260: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
b270: 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  R].** file-contr
b280: 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ol may be invoke
b290: 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74  d by SQLite on t
b2a0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
b2b0: 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74   handle.** short
b2c0: 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f  ly after it is o
b2d0: 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  pened in order t
b2e0: 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74  o provide a cust
b2f0: 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65  om VFS with acce
b300: 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e  ss.** to the con
b310: 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61  nections busy-ha
b320: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  ndler callback. 
b330: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
b340: 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a  of type (void **
b350: 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20  ).** - an array 
b360: 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20  of two (void *) 
b370: 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73  values. The firs
b380: 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61  t (void *) actua
b390: 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f  lly points.** to
b3a0: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
b3b0: 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69  ype (int (*)(voi
b3c0: 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20  d *)). In order 
b3d0: 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f  to invoke the co
b3e0: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73  nnections.** bus
b3f0: 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20  y-handler, this 
b400: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
b410: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
b420: 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64  the second (void
b430: 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72   *) in.** the ar
b440: 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ray as the only 
b450: 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20  argument. If it 
b460: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
b470: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61  , then the opera
b480: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
b490: 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74  e retried. If it
b4a0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
b4b0: 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68  he custom VFS sh
b4c0: 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65  ould abandon the
b4d0: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72  .** current oper
b4e0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
b4f0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b500: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a  TEMPFILENAME]].*
b510: 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63  * ^Application c
b520: 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53  an invoke the [S
b530: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
b540: 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63  FILENAME] file-c
b550: 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76  ontrol.** to hav
b560: 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74  e SQLite generat
b570: 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  e a.** temporary
b580: 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20   filename using 
b590: 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
b5a0: 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f  hm that is follo
b5b0: 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a  wed to generate.
b5c0: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
b5d0: 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20  enames for TEMP 
b5e0: 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72  tables and other
b5f0: 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20   internal uses. 
b600: 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   The.** argument
b610: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61   should be a cha
b620: 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62  r** which will b
b630: 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  e filled with th
b640: 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72  e filename.** wr
b650: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
b660: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
b670: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
b680: 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20  )].  The caller 
b690: 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65  should.** invoke
b6a0: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
b6b0: 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20  ] on the result 
b6c0: 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72  to avoid a memor
b6d0: 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  y leak..**.** <l
b6e0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b6f0: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
b700: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b710: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
b720: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e control is use
b730: 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65  d to query or se
b740: 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d  t the.** maximum
b750: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
b760: 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73   that will be us
b770: 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61  ed for memory-ma
b780: 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65  pped I/O..** The
b790: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
b7a0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75  ointer to a valu
b7b0: 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65  e of type sqlite
b7c0: 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20  3_int64 that.** 
b7d0: 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d  is an advisory m
b7e0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
b7f0: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
b800: 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70  le to memory map
b810: 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  .  The.** pointe
b820: 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  r is overwritten
b830: 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61   with the old va
b840: 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20  lue.  The limit 
b850: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69  is not changed i
b860: 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f  f.** the value o
b870: 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65  riginally pointe
b880: 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65  d to is negative
b890: 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72  , and so the cur
b8a0: 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63  rent limit .** c
b8b0: 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79  an be queried by
b8c0: 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f   passing in a po
b8d0: 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74  inter to a negat
b8e0: 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69  ive number.  Thi
b8f0: 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  s.** file-contro
b900: 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  l is used intern
b910: 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  ally to implemen
b920: 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  t [PRAGMA mmap_s
b930: 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ize]..**.** <li>
b940: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b950: 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  RACE]].** The [S
b960: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
b970: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
b980: 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72  provides advisor
b990: 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  y information.**
b9a0: 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75   to the VFS abou
b9b0: 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65  t what the highe
b9c0: 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20  r layers of the 
b9d0: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65  SQLite stack are
b9e0: 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20   doing..** This 
b9f0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
ba00: 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53  used by some VFS
ba10: 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e   activity tracin
ba20: 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68  g [shims]..** Th
ba30: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
ba40: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
ba50: 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20  string.  Higher 
ba60: 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a  layers in the.**
ba70: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61   SQLite stack ma
ba80: 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61  y generate insta
ba90: 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c  nces of this fil
baa0: 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20  e control if.** 
bab0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
bac0: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d  FCNTL_TRACE] com
bad0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
bae0: 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
baf0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
bb00: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
bb10: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
bb20: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
bb30: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
bb40: 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72  nterprets its ar
bb50: 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70  gument as a.** p
bb60: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
bb70: 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74  eger and it writ
bb80: 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74  es a boolean int
bb90: 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64  o that integer d
bba0: 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77  epending.** on w
bbb0: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
bbc0: 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20  e file has been 
bbd0: 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20  renamed, moved, 
bbe0: 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65  or deleted since
bbf0: 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74   it.** was first
bc00: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c   opened..**.** <
bc10: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bc20: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44  L_WIN32_GET_HAND
bc30: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  LE]].** The [SQL
bc40: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
bc50: 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f  GET_HANDLE] opco
bc60: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
bc70: 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a 20  o obtain the.** 
bc80: 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69 76  underlying nativ
bc90: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 73  e file handle as
bca0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
bcb0: 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54 68  file handle.  Th
bcc0: 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72  is file.** contr
bcd0: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
bce0: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 20  s argument as a 
bcf0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61 74  pointer to a nat
bd00: 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  ive file handle 
bd10: 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74 68  and.** writes th
bd20: 65 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c 75  e resulting valu
bd30: 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c  e there..**.** <
bd40: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bd50: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
bd60: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  LE]].** The [SQL
bd70: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
bd80: 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f  SET_HANDLE] opco
bd90: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
bda0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
bdb0: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
bdc0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
bdd0: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70  l method to swap
bde0: 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65   the file handle
bdf0: 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a   with the one.**
be00: 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
be10: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
be20: 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  .  This capabili
be30: 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ty is used durin
be40: 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64  g testing.** and
be50: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
be60: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
be70: 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20   SQLITE_TEST is 
be80: 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
be90: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bea0: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a  L_WAL_BLOCK]].**
beb0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
bec0: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73  TL_WAL_BLOCK] is
bed0: 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65   a signal to the
bee0: 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20   VFS layer that 
bef0: 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61  it might.** be a
bf00: 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62  dvantageous to b
bf10: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74  lock on the next
bf20: 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65   WAL lock if the
bf30: 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d   lock is not imm
bf40: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69  ediately.** avai
bf50: 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20  lable.  The WAL 
bf60: 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73  subsystem issues
bf70: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72   this signal dur
bf80: 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63  ing rare.** circ
bf90: 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64  umstances in ord
bfa0: 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62  er to fix a prob
bfb0: 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74  lem with priorit
bfc0: 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20  y inversion..** 
bfd0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
bfe0: 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e  uld <em>not</em>
bff0: 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63   use this file-c
c000: 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ontrol..**.** <l
c010: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c020: 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65  _ZIPVFS]].** The
c030: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a   [SQLITE_FCNTL_Z
c040: 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73  IPVFS] opcode is
c050: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
c060: 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c  zipvfs only. All
c070: 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68   other.** VFS sh
c080: 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49  ould return SQLI
c090: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20  TE_NOTFOUND for 
c0a0: 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a  this opcode..**.
c0b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c0c0: 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54  FCNTL_RBU]].** T
c0d0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c0e0: 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20  _RBU] opcode is 
c0f0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74  implemented by t
c100: 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75  he special VFS u
c110: 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42  sed by.** the RB
c120: 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79  U extension only
c130: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53  .  All other VFS
c140: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53   should return S
c150: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66  QLITE_NOTFOUND f
c160: 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64  or.** this opcod
c170: 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  e.  .** </ul>.*/
c180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c190: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
c1a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
c1b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c1c0: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_GET_LOCKPRO
c1d0: 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23  XYFILE       2.#
c1e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c1f0: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_SET_LOCKPROX
c200: 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64  YFILE       3.#d
c210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c220: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TL_LAST_ERRNO   
c230: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
c240: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c250: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20  L_SIZE_HINT     
c260: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
c270: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c280: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
c290: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
c2a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c2b0: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
c2c0: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
c2d0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
c2e0: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
c2f0: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
c300: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
c310: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20  N32_AV_RETRY    
c320: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
c330: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
c340: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20  SIST_WAL        
c350: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
c360: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
c370: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
c380: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51     11.#define SQ
c390: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
c3a0: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ME              
c3b0: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    12.#define SQL
c3c0: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
c3d0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
c3e0: 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   13.#define SQLI
c3f0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20  TE_FCNTL_PRAGMA 
c400: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c410: 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  14.#define SQLIT
c420: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
c430: 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31  LER            1
c440: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
c450: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
c460: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36  AME           16
c470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c480: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20  FCNTL_MMAP_SIZE 
c490: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a               18.
c4a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c4b0: 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20  CNTL_TRACE      
c4c0: 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23              19.#
c4d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c4e0: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20  NTL_HAS_MOVED   
c4f0: 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64             20.#d
c500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c510: 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20  TL_SYNC         
c520: 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65            21.#de
c530: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c540: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
c550: 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66  O        22.#def
c560: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c570: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
c580: 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69  E       23.#defi
c590: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c5a0: 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20  WAL_BLOCK       
c5b0: 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e         24.#defin
c5c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a  e SQLITE_FCNTL_Z
c5d0: 49 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20  IPVFS           
c5e0: 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65        25.#define
c5f0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42   SQLITE_FCNTL_RB
c600: 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  U               
c610: 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20       26.#define 
c620: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
c630: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
c640: 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53      27.#define S
c650: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
c660: 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  NAL_POINTER     
c670: 20 20 20 32 38 0a 23 64 65 66 69 6e 65 20 53 51     28.#define SQ
c680: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c690: 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20  _GET_HANDLE     
c6a0: 20 20 32 39 0a 23 64 65 66 69 6e 65 20 53 51 4c    29.#define SQL
c6b0: 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20  ITE_FCNTL_PDB   
c6c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c6d0: 20 33 30 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74   30../* deprecat
c6e0: 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66  ed names */.#def
c6f0: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
c700: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
c710: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47    SQLITE_FCNTL_G
c720: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c730: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c740: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
c750: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
c760: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_SET_LOCKPROX
c770: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
c780: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  LITE_LAST_ERRNO 
c790: 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c 49              SQLI
c7a0: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52  TE_FCNTL_LAST_ER
c7b0: 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  RNO.../*.** CAPI
c7c0: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
c7d0: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
c7e0: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
c7f0: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
c800: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
c810: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
c820: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
c830: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
c840: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
c850: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
c860: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
c870: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
c880: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
c890: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
c8a0: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
c8b0: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
c8c0: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
c8d0: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
c8e0: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
c8f0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
c900: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
c910: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
c920: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
c930: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
c940: 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
c950: 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 54  able Extension T
c960: 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  hunk.**.** A poi
c970: 6e 74 65 72 20 74 6f 20 74 68 65 20 6f 70 61 71  nter to the opaq
c980: 75 65 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ue sqlite3_api_r
c990: 6f 75 74 69 6e 65 73 20 73 74 72 75 63 74 75 72  outines structur
c9a0: 65 20 69 73 20 70 61 73 73 65 64 20 61 73 0a 2a  e is passed as.*
c9b0: 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  * the third para
c9c0: 6d 65 74 65 72 20 74 6f 20 65 6e 74 72 79 20 70  meter to entry p
c9d0: 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62  oints of [loadab
c9e0: 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20  le extensions]. 
c9f0: 20 54 68 69 73 0a 2a 2a 20 73 74 72 75 63 74 75   This.** structu
ca00: 72 65 20 6d 75 73 74 20 62 65 20 74 79 70 65 64  re must be typed
ca10: 65 66 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  efed in order to
ca20: 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d   work around com
ca30: 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a  piler warnings.*
ca40: 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f  * on some platfo
ca50: 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  rms..*/.typedef 
ca60: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61  struct sqlite3_a
ca70: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 71 6c 69  pi_routines sqli
ca80: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
ca90: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
caa0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
cab0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
cac0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
cad0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
cae0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
caf0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
cb00: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
cb10: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
cb20: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
cb30: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
cb40: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
cb50: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
cb60: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
cb70: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
cb80: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
cb90: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
cba0: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
cbb0: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
cbc0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
cbd0: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
cbe0: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
cbf0: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
cc00: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
cc10: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
cc20: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
cc30: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
cc40: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
cc50: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
cc60: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
cc70: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
cc80: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
cc90: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
cca0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
ccb0: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
ccc0: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
ccd0: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
cce0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
ccf0: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
cd00: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
cd10: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
cd20: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
cd30: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
cd40: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
cd50: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
cd60: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
cd70: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
cd80: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
cd90: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
cda0: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
cdb0: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
cdc0: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
cdd0: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
cde0: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
cdf0: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
ce00: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
ce10: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
ce20: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
ce30: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
ce40: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
ce50: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
ce60: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
ce70: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
ce80: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
ce90: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
cea0: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
ceb0: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
cec0: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
ced0: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
cee0: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
cef0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
cf00: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
cf10: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
cf20: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
cf30: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
cf40: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
cf50: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
cf60: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
cf70: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
cf80: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
cf90: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
cfa0: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
cfb0: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
cfc0: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
cfd0: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
cfe0: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
cff0: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
d000: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
d010: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
d020: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
d030: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
d040: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
d050: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
d060: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
d070: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
d080: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
d090: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
d0a0: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
d0b0: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
d0c0: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
d0d0: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
d0e0: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
d0f0: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
d100: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
d110: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
d120: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
d130: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
d140: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
d150: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
d160: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
d170: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
d180: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
d190: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
d1a0: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
d1b0: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
d1c0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
d1d0: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
d1e0: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
d1f0: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
d200: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
d210: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
d220: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
d230: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
d240: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
d250: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
d260: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
d270: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
d280: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
d290: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
d2a0: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
d2b0: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
d2c0: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
d2d0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
d2e0: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
d2f0: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
d300: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
d310: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
d320: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
d330: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
d340: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
d350: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
d360: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
d370: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
d380: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
d390: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
d3a0: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
d3b0: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
d3c0: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
d3d0: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
d3e0: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
d3f0: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
d400: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
d410: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
d420: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
d430: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
d440: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
d450: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
d460: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
d470: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
d480: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
d490: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
d4a0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
d4b0: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
d4c0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
d4d0: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
d4e0: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
d4f0: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
d500: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
d510: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
d520: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
d530: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
d540: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
d550: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
d560: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
d570: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
d580: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
d590: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
d5a0: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
d5b0: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
d5c0: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
d5d0: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
d5e0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
d5f0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
d600: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
d610: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
d620: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
d630: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
d640: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
d650: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d660: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
d670: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d680: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
d690: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
d6a0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
d6b0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d6c0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
d6d0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d6e0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
d6f0: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
d700: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
d710: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
d720: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d730: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
d740: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d750: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
d760: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
d770: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
d780: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
d790: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
d7a0: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
d7b0: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
d7c0: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
d7d0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
d7e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
d7f0: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
d800: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
d810: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
d820: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
d830: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
d840: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
d850: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
d860: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
d870: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
d880: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
d890: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
d8a0: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
d8b0: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
d8c0: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
d8d0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
d8e0: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
d8f0: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
d900: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
d910: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
d920: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
d930: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
d940: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
d950: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
d960: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
d970: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
d980: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
d990: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
d9a0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
d9b0: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
d9c0: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
d9d0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
d9e0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
d9f0: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
da00: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
da10: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
da20: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
da30: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
da40: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
da50: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
da60: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
da70: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
da80: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
da90: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
daa0: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
dab0: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
dac0: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
dad0: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
dae0: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
daf0: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
db00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
db10: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
db20: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
db30: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
db40: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
db50: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
db60: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
db70: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
db80: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
db90: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
dba0: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
dbb0: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
dbc0: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
dbd0: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
dbe0: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
dbf0: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
dc00: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
dc10: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
dc20: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
dc30: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
dc40: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
dc50: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
dc60: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
dc70: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
dc80: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
dc90: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
dca0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
dcb0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
dcc0: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
dcd0: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
dce0: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
dcf0: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
dd00: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
dd10: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
dd20: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
dd30: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
dd40: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
dd50: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
dd60: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
dd70: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
dd80: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
dd90: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
dda0: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
ddb0: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
ddc0: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
ddd0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
dde0: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
ddf0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
de00: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
de10: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
de20: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
de30: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
de40: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
de50: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
de60: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
de70: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
de80: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
de90: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
dea0: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
deb0: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
dec0: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
ded0: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
dee0: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
def0: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
df00: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
df10: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
df20: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
df30: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
df40: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
df50: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
df60: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
df70: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
df80: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
df90: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
dfa0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
dfb0: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
dfc0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
dfd0: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
dfe0: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
dff0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e000: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
e010: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
e020: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
e030: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
e040: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
e050: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
e060: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
e070: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
e080: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
e090: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
e0a0: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
e0b0: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
e0c0: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
e0d0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
e0e0: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
e0f0: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
e100: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
e110: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
e120: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
e130: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
e140: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
e150: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
e160: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
e170: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
e180: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
e190: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
e1a0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
e1b0: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
e1c0: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
e1d0: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
e1e0: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
e1f0: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
e200: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
e210: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
e220: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
e230: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
e240: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
e250: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
e260: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
e270: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
e280: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
e290: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
e2a0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
e2b0: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
e2c0: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
e2d0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
e2e0: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
e2f0: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
e300: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
e310: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
e320: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
e330: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
e340: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
e350: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
e360: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
e370: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
e380: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
e390: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
e3a0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
e3b0: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
e3c0: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
e3d0: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
e3e0: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
e3f0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
e400: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
e410: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
e420: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
e430: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
e440: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
e450: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
e460: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
e470: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
e480: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
e490: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
e4a0: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
e4b0: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
e4c0: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
e4d0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
e4e0: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
e4f0: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
e500: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
e510: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
e520: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
e530: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
e540: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
e550: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
e560: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
e570: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
e580: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
e590: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
e5a0: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
e5b0: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
e5c0: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
e5d0: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
e5e0: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
e5f0: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
e600: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
e610: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
e620: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
e630: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
e640: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
e650: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
e660: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
e670: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
e680: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
e690: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
e6a0: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
e6b0: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
e6c0: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
e6d0: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
e6e0: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
e6f0: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
e700: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
e710: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
e720: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
e730: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
e740: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
e750: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
e760: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
e770: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
e780: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
e790: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
e7a0: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
e7b0: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
e7c0: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
e7d0: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
e7e0: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
e7f0: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
e800: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
e810: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
e820: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
e830: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
e840: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
e850: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
e860: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
e870: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
e880: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
e890: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
e8a0: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
e8b0: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
e8c0: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
e8d0: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
e8e0: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
e8f0: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
e900: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
e910: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
e920: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
e930: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
e940: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
e950: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
e960: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
e970: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
e980: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
e990: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
e9a0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
e9b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
e9c0: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
e9d0: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
e9e0: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
e9f0: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
ea00: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
ea10: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
ea20: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
ea30: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
ea40: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
ea50: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
ea60: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
ea70: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
ea80: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
ea90: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
eaa0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
eab0: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
eac0: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
ead0: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
eae0: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
eaf0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
eb00: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
eb10: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
eb20: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
eb30: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
eb40: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
eb50: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
eb60: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
eb70: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
eb80: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
eb90: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
eba0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
ebb0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
ebc0: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
ebd0: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
ebe0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
ebf0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
ec00: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
ec10: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
ec20: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
ec30: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ec40: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
ec50: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
ec60: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
ec70: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
ec80: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ec90: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
eca0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
ecb0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
ecc0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
ecd0: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
ece0: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
ecf0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
ed00: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
ed10: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
ed20: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
ed30: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
ed40: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
ed50: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
ed60: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
ed70: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
ed80: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
ed90: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
eda0: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
edb0: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
edc0: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
edd0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
ede0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
edf0: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
ee00: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
ee10: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
ee20: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
ee30: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
ee40: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
ee50: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
ee60: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
ee70: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
ee80: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
ee90: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
eea0: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
eeb0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
eec0: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
eed0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
eee0: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
eef0: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
ef00: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
ef10: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
ef20: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
ef30: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
ef40: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
ef50: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
ef60: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
ef70: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
ef80: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ef90: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
efa0: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
efb0: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
efc0: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
efd0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
efe0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
eff0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
f000: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
f010: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
f020: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
f030: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
f040: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
f050: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
f060: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
f070: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
f080: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
f090: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
f0a0: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
f0b0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ed in future ver
f0c0: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
f0d0: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
f0e0: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
f0f0: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
f100: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
f110: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f120: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
f130: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
f140: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
f150: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
f160: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
f170: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
f180: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
f190: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
f1a0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
f1b0: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
f1c0: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
f1d0: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
f1e0: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
f1f0: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
f200: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
f210: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
f220: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
f230: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
f240: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
f250: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
f260: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
f270: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
f280: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
f290: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
f2a0: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
f2b0: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
f2c0: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
f2d0: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
f2e0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
f2f0: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
f300: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
f310: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
f320: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
f330: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
f340: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
f350: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
f360: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
f370: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
f380: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
f390: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
f3a0: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
f3b0: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
f3c0: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
f3d0: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
f3e0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f3f0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
f400: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
f410: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
f420: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
f430: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
f440: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
f450: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
f460: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
f470: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
f480: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
f490: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
f4a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f4b0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
f4c0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
f4d0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
f4e0: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
f4f0: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
f500: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
f510: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f520: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
f530: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
f540: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
f550: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
f560: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
f570: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
f580: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
f590: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
f5a0: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
f5b0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
f5c0: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
f5d0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
f5e0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
f5f0: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
f600: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
f610: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
f620: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
f630: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
f640: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
f650: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
f660: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
f670: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
f680: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
f690: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
f6a0: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
f6b0: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
f6c0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
f6d0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
f6e0: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
f6f0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
f700: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
f710: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
f720: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
f730: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
f740: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
f750: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
f760: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
f770: 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f   given on the co
f780: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
f790: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
f7a0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
f7b0: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
f7c0: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
f7d0: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
f7e0: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
f7f0: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
f800: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
f810: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
f820: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
f830: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
f840: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
f850: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
f860: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
f870: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
f880: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
f890: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
f8a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f8b0: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
f8c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f8d0: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
f8e0: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
f8f0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
f900: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
f910: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
f920: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
f930: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
f940: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
f950: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
f960: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
f970: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
f980: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
f990: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
f9a0: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
f9b0: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
f9c0: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
f9d0: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
f9e0: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
f9f0: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
fa00: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
fa10: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
fa20: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
fa30: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
fa40: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
fa50: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
fa60: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
fa70: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
fa80: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
fa90: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
faa0: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
fab0: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
fac0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
fad0: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
fae0: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
faf0: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
fb00: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
fb10: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
fb20: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
fb30: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
fb40: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
fb50: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
fb60: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
fb70: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
fb80: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
fb90: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
fba0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
fbb0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
fbc0: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
fbd0: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
fbe0: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
fbf0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fc00: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
fc10: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
fc20: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
fc30: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
fc40: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
fc50: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fc60: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
fc70: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
fc80: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
fc90: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
fca0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
fcb0: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
fcc0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
fcd0: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
fce0: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
fcf0: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
fd00: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
fd10: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
fd20: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
fd30: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
fd40: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
fd50: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
fd60: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
fd70: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
fd80: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
fd90: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fda0: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
fdb0: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
fdc0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
fdd0: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
fde0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
fdf0: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
fe00: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
fe10: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
fe20: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
fe30: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
fe40: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fe50: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
fe60: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
fe70: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
fe80: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
fe90: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
fea0: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
feb0: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
fec0: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
fed0: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
fee0: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
fef0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
ff00: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
ff10: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
ff20: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
ff30: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
ff40: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
ff50: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
ff60: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
ff70: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
ff80: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
ff90: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
ffa0: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
ffb0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
ffc0: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
ffd0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
ffe0: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
fff0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
10000 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
10010 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10020 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
10030 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
10040 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
10050 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
10060 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10070 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
10080 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
10090 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
100a0 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
100b0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
100c0 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
100d0 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
100e0 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
100f0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
10100 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
10110 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
10120 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
10130 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
10140 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
10150 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
10160 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
10170 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
10180 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
10190 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
101a0 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
101b0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
101c0 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
101d0 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
101e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
101f0 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
10200 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
10210 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
10220 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
10230 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
10240 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
10250 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
10260 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
10270 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
10280 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
10290 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
102a0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
102b0 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
102c0 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
102d0 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
102e0 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
102f0 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
10300 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
10310 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
10320 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
10330 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
10340 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
10350 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
10360 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
10370 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
10380 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
10390 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
103a0 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
103b0 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
103c0 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
103d0 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
103e0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
103f0 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
10400 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
10410 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
10420 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
10430 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
10440 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
10450 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
10460 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
10470 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
10480 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
10490 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
104a0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
104b0 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
104c0 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
104d0 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
104e0 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
104f0 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
10500 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
10510 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10520 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
10530 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
10540 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
10550 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
10560 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
10570 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
10580 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
10590 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
105a0 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
105b0 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
105c0 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
105d0 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
105e0 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
105f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
10600 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
10610 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
10620 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
10630 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
10640 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
10650 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
10660 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
10670 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
10680 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
10690 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
106a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
106b0 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
106c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
106d0 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
106e0 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
106f0 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
10700 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
10710 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
10720 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
10730 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
10740 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
10750 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
10760 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
10770 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
10780 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
10790 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
107a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
107b0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
107c0 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
107d0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
107e0 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
107f0 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
10800 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
10810 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
10820 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
10830 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
10840 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
10850 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
10860 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
10870 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
10880 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
10890 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
108a0 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
108b0 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
108c0 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
108d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
108e0 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
108f0 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
10900 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
10910 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
10920 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
10930 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
10940 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
10950 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
10960 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
10970 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
10980 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
10990 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
109a0 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
109b0 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
109c0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
109d0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
109e0 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
109f0 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
10a00 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53  ** failure..*/.S
10a10 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
10a20 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10a30 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
10a40 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
10a50 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53  hutdown(void);.S
10a60 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
10a70 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
10a80 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
10a90 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
10aa0 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
10ab0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
10ac0 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
10ad0 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
10ae0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
10af0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
10b00 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
10b10 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
10b20 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
10b30 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
10b40 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
10b50 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
10b60 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
10b70 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
10b80 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
10b90 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
10ba0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
10bb0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
10bc0 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
10bd0 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
10be0 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
10bf0 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
10c00 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
10c10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
10c20 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
10c30 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20  s..**.** <b>The 
10c40 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10c50 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
10c60 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68  t threadsafe. Th
10c70 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
10c80 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
10c90 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
10ca0 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
10cb0 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
10cc0 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
10cd0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
10ce0 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c  g() is running.<
10cf0 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  /b>.**.** The sq
10d00 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10d10 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20  nterface.** may 
10d20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
10d30 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
10d40 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
10d50 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
10d60 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
10d70 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
10d80 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
10d90 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
10da0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
10db0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
10dc0 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
10dd0 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
10de0 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
10df0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
10e00 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
10e10 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
10e20 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
10e30 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
10e40 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
10e50 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
10e60 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
10e70 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
10e80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
10e90 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
10ea0 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
10eb0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
10ec0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
10ed0 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
10ee0 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74  r.** [configurat
10ef0 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
10f00 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
10f10 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
10f20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
10f30 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
10f40 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
10f50 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
10f60 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66  ing on the [conf
10f70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10f80 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
10f90 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
10fa0 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
10fb0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
10fc0 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
10fd0 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
10fe0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
10ff0 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
11000 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
11010 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
11020 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
11030 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
11040 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
11050 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
11060 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ode]..*/.SQLITE_
11070 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
11080 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29  config(int, ...)
11090 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
110a0 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74  F: Configure dat
110b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
110c0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
110d0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite3.**.** The s
110e0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
110f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
11100 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
11110 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
11120 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
11130 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11140 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
11150 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
11160 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
11170 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
11180 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
11190 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
111a0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
111b0 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
111c0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
111d0 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
111e0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
111f0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
11200 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
11210 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
11220 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
11230 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
11240 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
11250 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
11260 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
11270 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
11280 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
11290 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
112a0 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
112b0 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
112c0 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
112d0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
112e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
112f0 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
11300 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
11310 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
11320 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
11330 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
11340 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
11350 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
11360 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
11370 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
11380 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
11390 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
113a0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
113b0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
113c0 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  tines.**.** An i
113d0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
113e0 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
113f0 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
11400 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ween SQLite.** a
11410 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  nd low-level mem
11420 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
11430 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
11440 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73  his object is us
11450 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70  ed in only one p
11460 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69  lace in the SQLi
11470 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
11480 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
11490 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
114a0 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20  s object is the 
114b0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b  argument to.** [
114c0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
114d0 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69  ] when the confi
114e0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
114f0 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  is.** [SQLITE_CO
11500 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20  NFIG_MALLOC] or 
11510 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
11520 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20  ETMALLOC].  .** 
11530 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69  By creating an i
11540 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
11550 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61  object.** and pa
11560 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
11570 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
11580 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
11590 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63  OC]).** during c
115a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e  onfiguration, an
115b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
115c0 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
115d0 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
115e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
115f0 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74  system for SQLit
11600 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c  e to use for all
11610 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d   of its.** dynam
11620 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e  ic memory needs.
11630 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
11640 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69   SQLite comes wi
11650 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c  th several [buil
11660 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
11670 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20  cators].** that 
11680 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64  are perfectly ad
11690 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f  equate for the o
116a0 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f  verwhelming majo
116b0 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
116c0 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74  ions.** and that
116d0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
116e0 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61  only useful to a
116f0 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f   tiny minority o
11700 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
11710 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a  * with specializ
11720 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
11730 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74  tion requirement
11740 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  s.  This object 
11750 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20  is.** also used 
11760 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f  during testing o
11770 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  f SQLite in orde
11780 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20  r to specify an 
11790 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
117a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
117b0 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d  that simulates m
117c0 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d  emory out-of-mem
117d0 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69  ory conditions i
117e0 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65  n.** order to ve
117f0 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
11800 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66   recovers gracef
11810 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a  ully from such.*
11820 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a  * conditions..**
11830 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c  .** The xMalloc,
11840 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78   xRealloc, and x
11850 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73  Free methods mus
11860 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a  t work like the.
11870 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  ** malloc(), rea
11880 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
11890 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d  ) functions from
118a0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
118b0 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c  library..** ^SQL
118c0 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
118d0 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61  hat the second a
118e0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52  rgument to.** xR
118f0 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73  ealloc is always
11900 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65   a value returne
11910 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c  d by a prior cal
11920 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a  l to xRoundup..*
11930 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
11940 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
11950 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
11960 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11970 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
11980 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
11990 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
119a0 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
119b0 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
119c0 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
119d0 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
119e0 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
119f0 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
11a00 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
11a10 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
11a20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
11a30 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
11a40 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
11a50 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
11a60 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
11a70 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
11a80 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
11a90 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
11aa0 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
11ab0 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
11ac0 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
11ad0 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
11ae0 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
11af0 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
11b00 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
11b10 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
11b20 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61  * Every memory a
11b30 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
11b40 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f  t coming in thro
11b50 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ugh [sqlite3_mal
11b60 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  loc()].** or [sq
11b70 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
11b80 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f   first calls xRo
11b90 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e  undup.  If xRoun
11ba0 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a  dup returns 0, .
11bb0 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74  ** that causes t
11bc0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
11bd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11be0 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  on to fail..**.*
11bf0 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
11c00 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
11c10 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
11c20 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tor.  For exampl
11c30 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
11c40 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
11c50 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
11c60 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
11c70 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
11c80 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
11c90 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
11ca0 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
11cb0 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
11cc0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
11cd0 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
11ce0 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
11cf0 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
11d00 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
11d10 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
11d20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
11d30 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
11d40 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
11d50 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
11d60 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
11d70 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
11d80 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
11d90 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
11da0 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
11db0 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
11dc0 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
11dd0 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
11de0 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
11df0 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
11e00 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
11e10 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
11e20 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
11e30 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
11e40 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
11e50 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
11e60 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
11e70 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
11e80 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
11e90 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
11ea0 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
11eb0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
11ec0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
11ed0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11ee0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
11ef0 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
11f00 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
11f10 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
11f20 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
11f30 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
11f40 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
11f50 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
11f60 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
11f70 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
11f80 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
11f90 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
11fa0 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
11fb0 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
11fc0 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
11fd0 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
11fe0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
11ff0 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
12000 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
12010 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
12020 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
12030 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
12040 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
12050 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
12060 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
12070 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
12080 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
12090 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
120a0 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
120b0 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
120c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
120d0 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
120e0 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
120f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
12100 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
12110 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
12120 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
12130 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
12140 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
12150 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
12160 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
12170 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
12180 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
12190 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
121a0 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
121b0 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
121c0 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
121d0 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
121e0 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
121f0 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
12200 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
12210 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
12220 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
12230 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
12240 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
12250 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
12260 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
12270 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
12280 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
12290 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
122a0 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
122b0 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
122c0 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
122d0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
122e0 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
122f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
12300 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12310 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion}.**.** These
12320 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
12330 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
12340 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
12350 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
12360 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
12370 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
12380 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
12390 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
123a0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
123b0 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
123c0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
123d0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
123e0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
123f0 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
12400 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
12410 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
12420 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
12430 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
12440 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
12450 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
12460 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
12470 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
12480 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
12490 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
124a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
124b0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
124c0 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
124d0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
124e0 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
124f0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
12500 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
12510 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
12520 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
12530 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
12540 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
12550 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
12560 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
12570 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
12580 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
12590 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
125a0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
125b0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
125c0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
125d0 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68  de] to Single-th
125e0 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
125f0 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
12600 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
12610 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
12620 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
12630 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
12640 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
12650 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
12660 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
12670 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
12680 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
12690 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
126a0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
126b0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
126c0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
126d0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
126e0 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72   change the [thr
126f0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f  eading mode] fro
12700 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a  m its default.**
12710 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65   value of Single
12720 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b  -thread and so [
12730 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12740 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a  ] will return .*
12750 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
12760 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
12770 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
12780 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a  G_SINGLETHREAD.*
12790 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
127a0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
127b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
127c0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d  IG_MULTITHREAD]]
127d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
127e0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
127f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
12800 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
12810 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
12820 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
12830 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
12840 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
12850 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
12860 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
12870 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
12880 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
12890 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
128a0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
128b0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
128c0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
128d0 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
128e0 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
128f0 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
12900 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12910 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
12920 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
12930 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
12940 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
12950 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
12960 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
12970 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
12980 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
12990 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
129a0 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
129b0 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
129c0 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
129d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
129e0 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
129f0 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
12a00 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12a10 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
12a20 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
12a30 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
12a40 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
12a50 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
12a60 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
12a70 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
12a80 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
12a90 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
12aa0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
12ab0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
12ac0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
12ad0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
12ae0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
12af0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
12b00 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
12b10 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
12b20 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12b30 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d  FIG_SERIALIZED]]
12b40 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12b50 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
12b60 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
12b70 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
12b80 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
12b90 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
12ba0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
12bb0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
12bc0 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
12bd0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
12be0 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
12bf0 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
12c00 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
12c10 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
12c20 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
12c30 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
12c40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
12c50 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
12c60 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
12c70 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
12c80 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
12c90 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12ca0 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
12cb0 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
12cc0 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
12cd0 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
12ce0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
12cf0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12d00 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
12d10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
12d20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
12d30 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
12d40 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
12d50 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
12d60 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
12d70 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
12d80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
12d90 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
12da0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
12db0 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
12dc0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12dd0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
12de0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
12df0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12e00 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
12e10 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
12e20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
12e30 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
12e40 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
12e50 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
12e60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12e70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
12e80 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
12e90 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
12ea0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
12eb0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
12ec0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12ed0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
12ee0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12ef0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
12f00 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12f10 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
12f20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
12f30 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  G_MALLOC option 
12f40 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
12f50 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
12f60 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
12f70 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
12f80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
12f90 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
12fa0 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
12fb0 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
12fc0 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
12fd0 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
12fe0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
12ff0 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
13000 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68  n place of.** th
13010 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
13020 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69  ion routines bui
13030 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
13040 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a  ^ ^SQLite makes.
13050 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ** its own priva
13060 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63  te copy of the c
13070 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
13080 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
13090 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ds] structure.**
130a0 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c   before the [sql
130b0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63  ite3_config()] c
130c0 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64  all returns.</dd
130d0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
130e0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
130f0 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
13100 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
13110 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13120 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13130 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f  _GETMALLOC optio
13140 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
13150 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
13160 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
13170 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
13180 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
13190 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
131a0 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73  cture..** The [s
131b0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
131c0 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
131d0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
131e0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
131f0 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
13200 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
13210 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
13220 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
13230 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
13240 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
13250 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
13260 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
13270 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
13280 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
13290 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
132a0 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
132b0 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
132c0 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ample. </dd>.**.
132d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
132e0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c  IG_MEMSTATUS]] <
132f0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13300 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
13310 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
13320 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
13330 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65  ATUS option take
13340 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
13350 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a  t of type int,.*
13360 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  * interpreted as
13370 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63   a boolean, whic
13380 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
13390 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
133a0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72  tion of.** memor
133b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
133c0 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20  tistics. ^(When 
133d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
133e0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
133f0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68  .** disabled, th
13400 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  e following SQLi
13410 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
13420 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
13430 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
13440 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
13450 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
13460 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
13470 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
13480 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
13490 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
134a0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
134b0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
134c0 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a  te3_status64()].
134d0 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
134e0 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
134f0 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
13500 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
13510 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
13520 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
13530 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
13540 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
13550 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
13560 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
13570 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
13580 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
13590 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
135a0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
135b0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
135c0 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  H]] <dt>SQLITE_C
135d0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
135e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
135f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
13600 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 65  RATCH option spe
13610 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
13620 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a  memory buffer.**
13630 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
13640 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 63 68   use for scratch
13650 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72   memory.  ^(Ther
13660 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
13670 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49  ments.** to SQLI
13680 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
13690 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e  H:  A pointer an
136a0 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
136b0 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ed memory buffer
136c0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
136d0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
136e0 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64  ons will be.** d
136f0 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f  rawn, the size o
13700 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61  f each scratch a
13710 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a  llocation (sz),.
13720 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ** and the maxim
13730 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72  um number of scr
13740 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
13750 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66   (N).)^.** The f
13760 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
13770 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
13780 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
13790 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
137a0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
137b0 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
137c0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
137d0 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 68   not use more th
137e0 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62  an one scratch b
137f0 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61  uffers per threa
13800 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  d..** ^SQLite wi
13810 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73 74  ll never request
13820 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
13830 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
13840 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74  han 6.** times t
13850 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
13860 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   size..** ^If SQ
13870 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73  Lite needs needs
13880 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73   additional.** s
13890 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65  cratch memory be
138a0 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
138b0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f  vided by this co
138c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
138d0 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71  on, then .** [sq
138e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
138f0 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20  will be used to 
13900 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72  obtain the memor
13910 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20  y needed.<p>.** 
13920 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69 63  ^When the applic
13930 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61  ation provides a
13940 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72  ny amount of scr
13950 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e  atch memory usin
13960 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  g.** SQLITE_CONF
13970 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c 69  IG_SCRATCH, SQLi
13980 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 65  te avoids unnece
13990 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b  ssary large.** [
139a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68  sqlite3_malloc|h
139b0 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d  eap allocations]
139c0 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 65  ..** This can he
139d0 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66  lp [Robson proof
139e0 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20  |prevent memory 
139f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
13a00 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61 70  res] due to heap
13a10 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  .** fragmentatio
13a20 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20  n in low-memory 
13a30 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
13a40 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
13a50 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13a60 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74  _PAGECACHE]] <dt
13a70 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
13a80 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
13a90 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
13aa0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
13ab0 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  HE option specif
13ac0 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f  ies a memory poo
13ad0 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  l.** that SQLite
13ae0 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65   can use for the
13af0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
13b00 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
13b10 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61  fault page.** ca
13b20 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
13b30 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
13b40 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13b50 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66  on is a no-op if
13b60 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
13b70 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
13b80 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
13b90 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
13ba0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
13bb0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e  CONFIG_PCACHE2].
13bc0 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
13bd0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
13be0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
13bf0 50 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69  PAGECACHE: A poi
13c00 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74  nter to.** 8-byt
13c10 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  e aligned memory
13c20 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a   (pMem), the siz
13c30 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 63  e of each page c
13c40 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a  ache line (sz),.
13c50 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ** and the numbe
13c60 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73  r of cache lines
13c70 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
13c80 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
13c90 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
13ca0 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
13cb0 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
13cc0 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
13cd0 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33  een 512 and 6553
13ce0 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74  6) plus some ext
13cf0 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 61 63  ra bytes for eac
13d00 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
13d10 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  .  ^The number o
13d20 66 20 65 78 74 72 61 20 62 79 74 65 73 20 6e 65  f extra bytes ne
13d30 65 64 65 64 20 62 79 20 74 68 65 20 70 61 67 65  eded by the page
13d40 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62   header.** can b
13d50 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
13d60 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ng [SQLITE_CONFI
13d70 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e  G_PCACHE_HDRSZ].
13d80 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  .** ^It is harml
13d90 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
13da0 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
13db0 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a  y,.** for the sz
13dc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
13dd0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63   larger than nec
13de0 65 73 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65  essary.  The pMe
13df0 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  m.** argument mu
13e00 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
13e10 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  ULL pointer or a
13e20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
13e30 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
13e40 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
13e50 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
13e60 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69  N bytes, otherwi
13e70 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  se.** subsequent
13e80 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
13e90 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e  efined..** ^When
13ea0 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c   pMem is not NUL
13eb0 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73  L, SQLite will s
13ec0 74 72 69 76 65 20 74 6f 20 75 73 65 20 74 68 65  trive to use the
13ed0 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
13ee0 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70  .** to satisfy p
13ef0 61 67 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c  age cache needs,
13f00 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f   falling back to
13f10 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13f20 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65  ()] if.** a page
13f30 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c   cache line is l
13f40 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79  arger than sz by
13f50 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66  tes or if all of
13f60 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72   the pMem buffer
13f70 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74 65 64  .** is exhausted
13f80 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73  ..** ^If pMem is
13f90 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e   NULL and N is n
13fa0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61  on-zero, then ea
13fb0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
13fc0 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61  ection.** does a
13fd0 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61  n initial bulk a
13fe0 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61  llocation for pa
13ff0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a  ge cache memory.
14000 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
14010 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69  _malloc()] suffi
14020 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68  cient for N cach
14030 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20  e lines if N is 
14040 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f  positive or.** o
14050 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20  f -1024*N bytes 
14060 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  if N is negative
14070 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  , . ^If addition
14080 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
14090 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
140a0 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
140b0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
140c0 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f   initial.** allo
140d0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c  cation, then SQL
140e0 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
140f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73  ite3_malloc()] s
14100 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61  eparately for ea
14110 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  ch.** additional
14120 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64   cache line. </d
14130 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14140 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
14150 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14160 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
14170 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
14180 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
14190 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
141a0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
141b0 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c  fer .** that SQL
141c0 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72  ite will use for
141d0 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
141e0 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
141f0 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62  ation needs.** b
14200 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
14210 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c  ided for by [SQL
14220 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
14230 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49  CH] and.** [SQLI
14240 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
14250 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51  CHE]..** ^The SQ
14260 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
14270 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
14280 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c  available if SQL
14290 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a  ite is compiled.
142a0 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 20 5b  ** with either [
142b0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
142c0 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54  MSYS3] or [SQLIT
142d0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
142e0 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  ] and returns.**
142f0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
14300 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72  if invoked other
14310 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  wise..** ^There 
14320 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
14330 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
14340 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e  NFIG_HEAP:.** An
14350 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
14360 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
14370 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
14380 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
14390 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
143a0 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
143b0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
143c0 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
143d0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
143e0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
143f0 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
14400 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
14410 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
14420 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
14430 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
14440 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
14450 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
14460 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
14470 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
14480 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
14490 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
144a0 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
144b0 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
144c0 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
144d0 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
144e0 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
144f0 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
14500 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
14510 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14520 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
14530 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
14540 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
14550 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
14560 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
14570 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
14580 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
14590 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
145a0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
145b0 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
145c0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
145d0 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
145e0 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
145f0 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
14600 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
14610 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
14620 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
14630 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14640 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
14650 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14660 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
14670 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14680 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f  E_CONFIG_MUTEX o
14690 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
146a0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
146b0 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ich is a.** poin
146c0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
146d0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
146e0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
146f0 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
14700 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
14710 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69  cifies alternati
14720 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
14730 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
14740 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61  e used.** in pla
14750 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ce the mutex rou
14760 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
14770 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c   SQLite.)^  ^SQL
14780 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
14790 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
147a0 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
147b0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
147c0 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f  ] structure befo
147d0 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  re the call to.*
147e0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
147f0 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49  g()] returns. ^I
14800 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
14810 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
14820 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
14830 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
14840 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
14850 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
14860 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
14870 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
14880 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
14890 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
148a0 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
148b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
148c0 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
148d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
148e0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
148f0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
14900 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
14910 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
14920 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14930 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c  FIG_GETMUTEX]] <
14940 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14950 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  _GETMUTEX</dt>.*
14960 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14970 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14980 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  TEX option takes
14990 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
149a0 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
149b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
149c0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
149d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
149e0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
149f0 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
14a00 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
14a10 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
14a20 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
14a30 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
14a40 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
14a50 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
14a60 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
14a70 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
14a80 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
14a90 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
14aa0 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
14ab0 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
14ac0 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
14ad0 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
14ae0 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
14af0 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
14b00 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
14b10 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14b20 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
14b30 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
14b40 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14b50 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
14b60 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
14b70 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
14b80 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
14b90 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
14ba0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
14bb0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
14bc0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14bd0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
14be0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
14bf0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14c00 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
14c10 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
14c20 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
14c30 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14c40 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e  LOOKASIDE]] <dt>
14c50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14c60 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
14c70 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14c80 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14c90 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  DE option takes 
14ca0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
14cb0 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  at determine.** 
14cc0 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65  the default size
14cd0 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65   of lookaside me
14ce0 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61  mory on each [da
14cf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14d00 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  n]..** The first
14d10 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
14d20 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
14d30 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
14d40 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73  r slot and the s
14d50 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d  econd is the num
14d60 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20  ber of.** slots 
14d70 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63  allocated to eac
14d80 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
14d90 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49  ction.)^  ^(SQLI
14da0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
14db0 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20  IDE.** sets the 
14dc0 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
14dd0 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
14de0 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
14df0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
14e00 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c  * option to [sql
14e10 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
14e20 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
14e30 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
14e40 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
14e50 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
14e60 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
14e70 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
14e80 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14e90 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
14ea0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14eb0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
14ec0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14ed0 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
14ee0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14ef0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
14f00 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  h is .** a point
14f10 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
14f20 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14f30 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73  2] object.  This
14f40 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
14f50 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61  s.** the interfa
14f60 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70  ce to a custom p
14f70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
14f80 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e  entation.)^.** ^
14f90 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
14fa0 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
14fb0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
14fc0 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64  ds2] object.</dd
14fd0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14fe0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
14ff0 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
15000 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15010 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
15020 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
15030 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70  IG_GETPCACHE2 op
15040 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
15050 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
15060 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
15070 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
15080 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
15090 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  2] object.  SQLi
150a0 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20  te copies of.** 
150b0 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 67 65  the current page
150c0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
150d0 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
150e0 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a  object.)^ </dd>.
150f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15100 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e  ONFIG_LOG]] <dt>
15110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15120 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54  G</dt>.** <dd> T
15130 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15140 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75  _LOG option is u
15150 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
15160 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67   the SQLite.** g
15170 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67  lobal [error log
15180 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49  ]..** (^The SQLI
15190 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
151a0 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
151b0 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e  rguments: a poin
151c0 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63  ter to a.** func
151d0 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c  tion with a call
151e0 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f   signature of vo
151f0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  id(*)(void*,int,
15200 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a  const char*), .*
15210 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20  * and a pointer 
15220 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65  to void. ^If the
15230 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
15240 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69  r is not NULL, i
15250 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  t is.** invoked 
15260 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  by [sqlite3_log(
15270 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61  )] to process ea
15280 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74  ch logging event
15290 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75  .  ^If the.** fu
152a0 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
152b0 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c  s NULL, the [sql
152c0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65  ite3_log()] inte
152d0 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20  rface becomes a 
152e0 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76  no-op..** ^The v
152f0 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74  oid pointer that
15300 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   is the second a
15310 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54  rgument to SQLIT
15320 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a  E_CONFIG_LOG is.
15330 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  ** passed throug
15340 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70  h as the first p
15350 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
15360 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
15370 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
15380 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20  nction whenever 
15390 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73  that function is
153a0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20   invoked.  ^The 
153b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
153c0 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65   to.** the logge
153d0 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20  r function is a 
153e0 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73  copy of the firs
153f0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
15400 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
15410 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  .** [sqlite3_log
15420 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20  ()] call and is 
15430 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61  intended to be a
15440 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
15450 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  r an.** [extende
15460 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20  d result code]. 
15470 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
15480 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
15490 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a  the logger is.**
154a0 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74   log message aft
154b0 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69  er formatting vi
154c0 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  a [sqlite3_snpri
154d0 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53  ntf()]..** The S
154e0 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e  QLite logging in
154f0 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
15500 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f  eentrant; the lo
15510 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gger function.**
15520 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65   supplied by the
15530 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
15540 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79  t not invoke any
15550 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
15560 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69  e..** In a multi
15570 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63  -threaded applic
15580 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69  ation, the appli
15590 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
155a0 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
155b0 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  n must be thread
155c0 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  safe. </dd>.**.*
155d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
155e0 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_URI]] <dt>SQLI
155f0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a  TE_CONFIG_URI.**
15600 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54   <dd>^(The SQLIT
15610 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74  E_CONFIG_URI opt
15620 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
15630 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
15640 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e  ype int..** If n
15650 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52  on-zero, then UR
15660 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
15670 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20  obally enabled. 
15680 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
15690 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65   is zero,.** the
156a0 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
156b0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
156c0 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68  led.)^ ^If URI h
156d0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
156e0 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20  lly.** enabled, 
156f0 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61  all filenames pa
15700 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
15710 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
15720 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a  e3_open_v2()],.*
15730 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
15740 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
15750 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
15760 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
15770 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
15780 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
15790 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
157a0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
157b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
157c0 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
157d0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
157e0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
157f0 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69  opened. ^If it i
15800 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
15810 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
15820 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
15830 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
15840 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
15850 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
15860 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
15870 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15880 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42  n is opened. ^(B
15890 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68  y default, URI h
158a0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
158b0 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  lly.** disabled.
158c0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
158d0 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65  ue may be change
158e0 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77  d by compiling w
158f0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
15900 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62  TE_USE_URI] symb
15910 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a  ol defined.)^.**
15920 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15930 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
15940 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
15950 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
15960 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
15970 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15980 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
15990 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70  NG_INDEX_SCAN op
159a0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
159b0 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61  gle integer.** a
159c0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
159d0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
159e0 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64  a boolean in ord
159f0 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  er to enable or 
15a00 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75  disable.** the u
15a10 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
15a20 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20  ndices for full 
15a30 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74  table scans in t
15a40 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  he query optimiz
15a50 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  er..** ^The defa
15a60 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64  ult setting is d
15a70 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20  etermined.** by 
15a80 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f  the [SQLITE_ALLO
15a90 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  W_COVERING_INDEX
15aa0 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SCAN] compile-t
15ab0 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69  ime option, or i
15ac0 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61  s "on".** if tha
15ad0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
15ae0 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ption is omitted
15af0 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79  ..** The ability
15b00 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20   to disable the 
15b10 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
15b20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
15b30 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20   table scans.** 
15b40 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20  is because some 
15b50 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65  incorrectly code
15b60 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61  d legacy applica
15b70 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66  tions might malf
15b80 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20  unction.** when 
15b90 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
15ba0 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72   is enabled.  Pr
15bb0 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c  oviding the abil
15bc0 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c  ity to.** disabl
15bd0 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  e the optimizati
15be0 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c  on allows the ol
15bf0 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69  der, buggy appli
15c00 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77  cation code to w
15c10 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63  ork.** without c
15c20 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20  hange even with 
15c30 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
15c40 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
15c50 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15c60 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
15c70 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
15c80 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
15c90 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15ca0 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
15cb0 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
15cc0 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
15cd0 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
15ce0 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
15cf0 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
15d00 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
15d10 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
15d20 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
15d30 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
15d40 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64   no-ops..** </dd
15d50 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15d60 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d  _CONFIG_SQLLOG]]
15d70 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
15d80 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20  ONFIG_SQLLOG.** 
15d90 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
15da0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
15db0 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63  e if sqlite is c
15dc0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
15dd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
15de0 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70  LE_SQLLOG] pre-p
15df0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64  rocessor macro d
15e00 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73  efined. The firs
15e10 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  t argument shoul
15e20 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65  d.** be a pointe
15e30 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  r to a function 
15e40 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28  of type void(*)(
15e50 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63  void*,sqlite3*,c
15e60 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
15e70 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
15e80 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70  should be of typ
15e90 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63  e (void*). The c
15ea0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
15eb0 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72  ed by the librar
15ec0 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65  y.** in three se
15ed0 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61  parate circumsta
15ee0 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64  nces, identified
15ef0 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61   by the value pa
15f00 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66  ssed as the.** f
15f10 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e  ourth parameter.
15f20 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
15f30 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74  arameter is 0, t
15f40 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
15f50 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70   connection.** p
15f60 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
15f70 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73  ond argument has
15f80 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65   just been opene
15f90 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67  d. The third arg
15fa0 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20  ument.** points 
15fb0 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74  to a buffer cont
15fc0 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20  aining the name 
15fd0 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  of the main data
15fe0 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68  base file. If th
15ff0 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
16000 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e  meter is 1, then
16010 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
16020 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72  nt that the thir
16030 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70  d parameter.** p
16040 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73  oints to has jus
16050 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e  t been executed.
16060 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72   Or, if the four
16070 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
16080 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63  2, then.** the c
16090 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20  onnection being 
160a0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
160b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
160c0 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20  s being closed. 
160d0 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  The.** third par
160e0 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64  ameter is passed
160f0 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61   NULL In this ca
16100 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  se.  An example 
16110 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a  of using this.**
16120 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
16130 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65  ption can be see
16140 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73  n in the "test_s
16150 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20  qllog.c" source 
16160 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63  file in.** the c
16170 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20  anonical SQLite 
16180 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64  source tree.</dd
16190 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
161a0 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
161b0 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
161c0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
161d0 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54  ZE.** <dd>^SQLIT
161e0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
161f0 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d  ZE takes two 64-
16200 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c  bit integer (sql
16210 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75  ite3_int64) valu
16220 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74  es.** that are t
16230 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20  he default mmap 
16240 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20  size limit (the 
16250 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
16260 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d  for.** [PRAGMA m
16270 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74  map_size]) and t
16280 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
16290 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  ed mmap size lim
162a0 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  it..** ^The defa
162b0 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20  ult setting can 
162c0 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  be overridden by
162d0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
162e0 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a  onnection using.
162f0 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50  ** either the [P
16300 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
16310 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20   command, or by 
16320 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
16330 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
16340 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
16350 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d  ol.  ^(The maxim
16360 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
16370 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  size.** will be 
16380 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
16390 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 79 20  ed if necessary 
163a0 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73 20  so that it does 
163b0 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a  not exceed the.*
163c0 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  * compile-time m
163d0 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65  aximum mmap size
163e0 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b   set by the.** [
163f0 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f  SQLITE_MAX_MMAP_
16400 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SIZE] compile-ti
16410 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20  me option.)^.** 
16420 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d  ^If either argum
16430 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69  ent to this opti
16440 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  on is negative, 
16450 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65  then that argume
16460 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64  nt is.** changed
16470 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d   to its compile-
16480 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  time default..**
16490 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
164a0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
164b0 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
164c0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
164d0 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  HEAPSIZE.** <dd>
164e0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
164f0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
16500 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  E option is only
16510 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
16520 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
16530 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20  led for Windows 
16540 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
16550 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70  _WIN32_MALLOC] p
16560 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
16570 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e  ro.** defined. ^
16580 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
16590 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b  N32_HEAPSIZE tak
165a0 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69  es a 32-bit unsi
165b0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c  gned integer val
165c0 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69  ue.** that speci
165d0 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  fies the maximum
165e0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65   size of the cre
165f0 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a  ated heap..**.**
16600 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16610 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a  _PCACHE_HDRSZ]].
16620 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16630 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
16640 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
16650 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
16660 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20  HE_HDRSZ option 
16670 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
16680 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
16690 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
166a0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
166b0 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61   writes into tha
166c0 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75  t integer the nu
166d0 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a  mber of extra.**
166e0 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65 20   bytes per page 
166f0 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61 63  required for eac
16700 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54  h page in [SQLIT
16710 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
16720 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75  HE]..** The amou
16730 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61 63  nt of extra spac
16740 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20 63  e required can c
16750 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20  hange depending 
16760 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c  on the compiler,
16770 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66  .** target platf
16780 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20  orm, and SQLite 
16790 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  version..**.** [
167a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
167b0 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  MASZ]].** <dt>SQ
167c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
167d0 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
167e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
167f0 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
16800 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
16810 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e  r which.** is an
16820 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
16830 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20 22  r and sets the "
16840 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  Minimum PMA Size
16850 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74  " for the multit
16860 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65  hreaded.** sorte
16870 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  r to that intege
16880 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  r.  The default 
16890 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  minimum PMA Size
168a0 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a   is set by the.*
168b0 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52  * [SQLITE_SORTER
168c0 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d  _PMASZ] compile-
168d0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65  time option.  Ne
168e0 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c 61  w threads are la
168f0 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c  unched.** to hel
16900 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72  p with sort oper
16910 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74  ations when mult
16920 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e  ithreaded sortin
16930 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20  g.** is enabled 
16940 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47  (using the [PRAG
16950 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d  MA threads] comm
16960 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f  and) and the amo
16970 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a  unt of content.*
16980 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65  * to be sorted e
16990 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65 20  xceeds the page 
169a0 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d  size times the m
169b0 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a  inimum of the.**
169c0 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73   [PRAGMA cache_s
169d0 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64  ize] setting and
169e0 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a   this value..**.
169f0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16a00 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
16a10 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  L]].** <dt>SQLIT
16a20 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
16a30 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e  L_SPILL.** <dd>^
16a40 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16a50 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
16a60 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
16a70 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
16a80 20 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65   which.** become
16a90 73 20 74 68 65 20 5b 73 74 61 74 65 6d 65 6e 74  s the [statement
16aa0 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d   journal] spill-
16ab0 74 6f 2d 64 69 73 6b 20 74 68 72 65 73 68 6f 6c  to-disk threshol
16ac0 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65  d.  .** [Stateme
16ad0 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65  nt journals] are
16ae0 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20   held in memory 
16af0 75 6e 74 69 6c 20 74 68 65 69 72 20 73 69 7a 65  until their size
16b00 20 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65   (in bytes).** e
16b10 78 63 65 65 64 73 20 74 68 69 73 20 74 68 72 65  xceeds this thre
16b20 73 68 6f 6c 64 2c 20 61 74 20 77 68 69 63 68 20  shold, at which 
16b30 70 6f 69 6e 74 20 74 68 65 79 20 61 72 65 20 77  point they are w
16b40 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a  ritten to disk..
16b50 2a 2a 20 4f 72 20 69 66 20 74 68 65 20 74 68 72  ** Or if the thr
16b60 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74  eshold is -1, st
16b70 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73  atement journals
16b80 20 61 72 65 20 61 6c 77 61 79 73 20 68 65 6c 64   are always held
16b90 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c 79 20  .** exclusively 
16ba0 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69  in memory..** Si
16bb0 6e 63 65 20 6d 61 6e 79 20 73 74 61 74 65 6d 65  nce many stateme
16bc0 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65  nt journals neve
16bd0 72 20 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20  r become large, 
16be0 73 65 74 74 69 6e 67 20 74 68 65 20 73 70 69 6c  setting the spil
16bf0 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20 74  l.** threshold t
16c00 6f 20 61 20 76 61 6c 75 65 20 73 75 63 68 20 61  o a value such a
16c10 73 20 36 34 4b 69 42 20 63 61 6e 20 67 72 65 61  s 64KiB can grea
16c20 74 6c 79 20 72 65 64 75 63 65 20 74 68 65 20 61  tly reduce the a
16c30 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20  mount of.** I/O 
16c40 72 65 71 75 69 72 65 64 20 74 6f 20 73 75 70 70  required to supp
16c50 6f 72 74 20 73 74 61 74 65 6d 65 6e 74 20 72 6f  ort statement ro
16c60 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64  llback..** The d
16c70 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
16c80 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73   this setting is
16c90 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74   controlled by t
16ca0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54  he.** [SQLITE_ST
16cb0 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f  MTJRNL_SPILL] co
16cc0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
16cd0 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  n..** </dl>.*/.#
16ce0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16cf0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
16d00 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
16d10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16d20 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
16d30 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
16d40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16d50 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
16d60 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
16d70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16d80 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
16d90 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
16da0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
16db0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16dc0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
16dd0 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
16de0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
16df0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
16e00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
16e10 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
16e20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
16e30 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
16e40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
16e50 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
16e60 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
16e70 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
16e80 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16e90 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
16ea0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
16eb0 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
16ec0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16ed0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
16ee0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
16ef0 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
16f00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
16f10 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
16f20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
16f30 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
16f40 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16f50 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
16f60 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
16f70 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
16f80 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
16f90 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
16fa0 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
16fb0 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
16fc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16fd0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16fe0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
16ff0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
17000 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17010 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
17020 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
17030 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
17040 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
17050 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
17060 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17070 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
17080 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
17090 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
170a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
170b0 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
170c0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
170d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
170e0 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a  CHE2      18  /*
170f0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
17100 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
17110 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17120 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20  IG_GETPCACHE2   
17130 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  19  /* sqlite3_p
17140 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
17150 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17160 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
17170 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20  G_INDEX_SCAN 20 
17180 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
17190 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
171a0 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31  _SQLLOG       21
171b0 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f    /* xSqllog, vo
171c0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
171d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
171e0 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a  P_SIZE    22  /*
171f0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20   sqlite3_int64, 
17200 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f  sqlite3_int64 */
17210 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17220 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
17230 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f  PSIZE      23  /
17240 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23  * int nByte */.#
17250 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17260 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
17270 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20  Z        24  /* 
17280 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66  int *psz */.#def
17290 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
172a0 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20  G_PMASZ         
172b0 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73        25  /* uns
172c0 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20  igned int szPma 
172d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
172e0 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
172f0 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20  L_SPILL      26 
17300 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
17310 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17320 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
17330 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
17340 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
17350 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
17360 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
17370 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
17380 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17390 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
173a0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
173b0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
173c0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
173d0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
173e0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
173f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
17400 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
17410 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
17420 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
17430 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
17440 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
17450 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
17460 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
17470 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
17480 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
17490 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
174a0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
174b0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
174c0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
174d0 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
174e0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
174f0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
17500 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
17510 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
17520 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
17530 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
17540 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
17550 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
17560 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
17570 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
17580 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
17590 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
175a0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
175b0 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
175c0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
175d0 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
175e0 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
175f0 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
17600 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
17610 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
17620 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17630 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
17640 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
17650 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
17660 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
17670 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
17680 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
17690 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
176a0 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
176b0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
176c0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
176d0 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
176e0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
176f0 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
17700 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
17710 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
17720 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
17730 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
17740 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
17750 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
17760 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
17770 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
17780 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
17790 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
177a0 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
177b0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
177c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
177d0 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
177e0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
177f0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
17800 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
17810 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
17820 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
17830 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
17840 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
17850 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
17860 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
17870 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
17880 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
17890 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
178a0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
178b0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
178c0 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
178d0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
178e0 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
178f0 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
17900 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
17910 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
17920 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
17930 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
17940 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
17950 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
17960 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
17970 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
17980 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
17990 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
179a0 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
179b0 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
179c0 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
179d0 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
179e0 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
179f0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
17a00 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
17a10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
17a20 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
17a30 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
17a40 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
17a50 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
17a60 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
17a70 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
17a80 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
17a90 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
17aa0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
17ab0 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
17ac0 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
17ad0 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
17ae0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
17af0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
17b00 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
17b10 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
17b20 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
17b30 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
17b40 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
17b50 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
17b60 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
17b70 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
17b80 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
17b90 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
17ba0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
17bb0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
17bc0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
17bd0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
17be0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
17bf0 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
17c00 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
17c10 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
17c20 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
17c30 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
17c40 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
17c50 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17c60 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
17c70 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
17c80 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
17c90 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
17ca0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
17cb0 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
17cc0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
17cd0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
17ce0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
17cf0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
17d00 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
17d10 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
17d20 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
17d30 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
17d40 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
17d50 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17d60 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
17d70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
17d80 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
17d90 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
17da0 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
17db0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
17dc0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
17dd0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
17de0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
17df0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
17e00 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
17e10 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
17e20 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
17e30 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
17e40 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
17e50 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
17e60 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
17e70 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
17e80 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
17e90 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
17ea0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
17eb0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
17ec0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
17ed0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
17ee0 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
17ef0 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
17f00 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
17f10 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
17f20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17f30 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
17f40 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
17f50 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
17f60 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
17f70 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
17f80 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
17f90 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
17fa0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54  CONFIG_ENABLE_FT
17fb0 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74  S3_TOKENIZER</dt
17fc0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
17fd0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
17fe0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
17ff0 62 6c 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75  ble the two-argu
18000 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20  ment.** version 
18010 6f 66 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b  of the [fts3_tok
18020 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69  enizer()] functi
18030 6f 6e 20 77 68 69 63 68 20 69 73 20 70 61 72 74  on which is part
18040 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33   of the.** [FTS3
18050 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72  ] full-text sear
18060 63 68 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73  ch engine extens
18070 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  ion..** There sh
18080 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
18090 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
180a0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
180b0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
180c0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
180d0 20 74 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33   to disable fts3
180e0 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a  _tokenizer() or.
180f0 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
18100 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e  nable fts3_token
18110 69 7a 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69  izer() or negati
18120 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
18130 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61  setting.** uncha
18140 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
18150 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
18160 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
18170 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
18180 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
18190 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
181a0 63 61 74 65 20 77 68 65 74 68 65 72 20 66 74 73  cate whether fts
181b0 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64  3_tokenizer is d
181c0 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
181d0 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
181e0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
181f0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18200 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
18210 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
18220 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77  ich case the new
18230 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
18240 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
18250 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
18260 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
18270 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e  NABLE_LOAD_EXTEN
18280 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SION</dt>.** <dd
18290 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
182a0 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
182b0 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
182c0 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
182d0 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e  tension()].** in
182e0 74 65 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64  terface independ
182f0 65 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f  ently of the [lo
18300 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
18310 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  SQL function..**
18320 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e   The [sqlite3_en
18330 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
18340 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c  ion()] API enabl
18350 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62  es or disables b
18360 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49  oth the.** C-API
18370 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
18380 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20  xtension()] and 
18390 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
183a0 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e   [load_extension
183b0 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  ()]..** There sh
183c0 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
183d0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
183e0 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69  ..** When the fi
183f0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
18400 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
18410 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74  s 1, then only t
18420 68 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65  he C-API is.** e
18430 6e 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53  nabled and the S
18440 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61  QL function rema
18450 69 6e 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49  ins disabled.  I
18460 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  f the first argu
18470 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20  ment to.** this 
18480 69 6e 74 65 72 66 61 63 65 20 69 73 20 30 2c 20  interface is 0, 
18490 74 68 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d  then both the C-
184a0 41 50 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20  API and the SQL 
184b0 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73  function are dis
184c0 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  abled..** If the
184d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
184e0 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63  is -1, then no c
184f0 68 61 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20  hanges are made 
18500 74 6f 20 73 74 61 74 65 20 6f 66 20 65 69 74 68  to state of eith
18510 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20  er the.** C-API 
18520 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  or the SQL funct
18530 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ion..** The seco
18540 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
18550 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
18560 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
18570 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
18580 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
18590 61 74 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c  ate whether [sql
185a0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
185b0 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ion()] interface
185c0 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20  .** is disabled 
185d0 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f  or enabled follo
185e0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
185f0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18600 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20  meter may.** be 
18610 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
18620 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
18630 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73  e new setting is
18640 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
18650 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ck..** </dd>.**.
18660 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
18670 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d  CONFIG_MAINDBNAM
18680 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
18690 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
186a0 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  sed to change th
186b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d  e name of the "m
186c0 61 69 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a  ain" database.**
186d0 20 73 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73   schema.  ^The s
186e0 6f 6c 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ole argument is 
186f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63  a pointer to a c
18700 6f 6e 73 74 61 6e 74 20 55 54 46 38 20 73 74 72  onstant UTF8 str
18710 69 6e 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c  ing.** which wil
18720 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77  l become the new
18730 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20   schema name in 
18740 70 6c 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e  place of "main".
18750 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65    ^SQLite.** doe
18760 73 20 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70  s not make a cop
18770 79 20 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69  y of the new mai
18780 6e 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74  n schema name st
18790 72 69 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70  ring, so the app
187a0 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
187b0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
187c0 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
187d0 20 69 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e   into this DBCON
187e0 46 49 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  FIG option is un
187f0 63 68 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c  changed.** until
18800 20 61 66 74 65 72 20 74 68 65 20 64 61 74 61 62   after the datab
18810 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
18820 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  loses..** </dd>.
18830 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
18840 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50  _DBCONFIG_NO_CKP
18850 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a  T_ON_CLOSE</dt>.
18860 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c  ** <dd> Usually,
18870 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
18880 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20   in wal mode is 
18890 63 6c 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68  closed or detach
188a0 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61  ed from a .** da
188b0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53  tabase handle, S
188c0 51 4c 69 74 65 20 63 68 65 63 6b 73 20 69 66 20  QLite checks if 
188d0 74 68 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74  this will mean t
188e0 68 61 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hat there are no
188f0 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  w no .** connect
18900 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74  ions at all to t
18910 68 65 20 64 61 74 61 62 61 73 65 2e 20 49 66 20  he database. If 
18920 73 6f 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20  so, it performs 
18930 61 20 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a  a checkpoint .**
18940 20 6f 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72   operation befor
18950 65 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f  e closing the co
18960 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f  nnection. This o
18970 70 74 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65  ption may be use
18980 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65  d to.** override
18990 20 74 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e   this behaviour.
189a0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
189b0 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  eter passed to t
189c0 68 69 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  his operation.**
189d0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d   is an integer -
189e0 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20 64 69 73   non-zero to dis
189f0 61 62 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73  able checkpoints
18a00 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65  -on-close, or ze
18a10 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75  ro (the.** defau
18a20 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68  lt) to enable th
18a30 65 6d 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  em. The second p
18a40 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
18a50 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
18a60 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63  ger.** into whic
18a70 68 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  h is written 0 o
18a80 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
18a90 77 68 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69  whether checkpoi
18aa0 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20  nts-on-close.** 
18ab0 68 61 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c  have been disabl
18ac0 65 64 20 2d 20 30 20 69 66 20 74 68 65 79 20 61  ed - 0 if they a
18ad0 72 65 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c  re not disabled,
18ae0 20 31 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a   1 if they are..
18af0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
18b00 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
18b10 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18b20 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20  MAINDBNAME      
18b30 20 20 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f        1000 /* co
18b40 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65  nst char* */.#de
18b50 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
18b60 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
18b70 20 20 20 20 20 20 20 20 20 20 20 31 30 30 31 20             1001 
18b80 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74  /* void* int int
18b90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18ba0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18bb0 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20  LE_FKEY         
18bc0 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e    1002 /* int in
18bd0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
18be0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18bf0 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20  ABLE_TRIGGER    
18c00 20 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20      1003 /* int 
18c10 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
18c20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18c30 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45  ENABLE_FTS3_TOKE
18c40 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e  NIZER 1004 /* in
18c50 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
18c60 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
18c70 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58  G_ENABLE_LOAD_EX
18c80 54 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20  TENSION 1005 /* 
18c90 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
18ca0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
18cb0 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43  FIG_NO_CKPT_ON_C
18cc0 4c 4f 53 45 20 20 20 20 20 20 31 30 30 36 20 2f  LOSE      1006 /
18cd0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a  * int int* */...
18ce0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18cf0 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
18d00 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
18d10 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f  t Codes.** METHO
18d20 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
18d30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
18d40 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
18d50 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
18d60 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
18d70 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
18d80 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
18d90 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
18da0 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
18db0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
18dc0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
18dd0 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
18de0 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
18df0 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54  bility..*/.SQLIT
18e00 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
18e10 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
18e20 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
18e30 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
18e40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
18e50 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
18e60 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
18e70 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  te3.**.** ^Each 
18e80 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51  entry in most SQ
18e90 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63  Lite tables (exc
18ea0 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54  ept for [WITHOUT
18eb0 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a   ROWID] tables).
18ec0 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  ** has a unique 
18ed0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
18ee0 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
18ef0 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
18f00 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
18f10 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
18f20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
18f30 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
18f40 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
18f50 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
18f60 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
18f70 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
18f80 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
18f90 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
18fa0 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
18fb0 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
18fc0 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
18fd0 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
18fe0 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
18ff0 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
19000 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
19010 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
19020 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
19030 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
19040 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20  id(D) interface 
19050 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
19060 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d  id] of the .** m
19070 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65  ost recent succe
19080 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
19090 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c  nto a rowid tabl
190a0 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61  e or [virtual ta
190b0 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62  ble].** on datab
190c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
190d0 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e  ..** ^Inserts in
190e0 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  to [WITHOUT ROWI
190f0 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f  D] tables are no
19100 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e  t recorded..** ^
19110 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
19120 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20   [INSERT]s into 
19130 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20  rowid tables.** 
19140 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
19150 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ed on the databa
19160 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c  se connection D,
19170 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65   .** then sqlite
19180 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
19190 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a  wid(D) returns z
191a0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ero..**.** ^(If 
191b0 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75  an [INSERT] occu
191c0 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
191d0 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20  ger or within a 
191e0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
191f0 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  ** method, then 
19200 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
19210 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  l return the [ro
19220 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
19230 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c  rted.** row as l
19240 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
19250 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
19260 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75  ble method is ru
19270 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
19280 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  ce the trigger o
19290 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
192a0 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65  method ends, the
192b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
192c0 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
192d0 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77  ine reverts to w
192e0 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72  hat it was befor
192f0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
19300 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c   virtual.** tabl
19310 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29  e method began.)
19320 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
19330 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
19340 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
19350 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
19360 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
19370 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
19380 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
19390 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
193a0 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
193b0 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
193c0 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
193d0 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
193e0 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
193f0 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
19400 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
19410 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
19420 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
19430 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
19440 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
19450 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
19460 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
19470 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
19480 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
19490 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
194a0 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
194b0 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
194c0 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
194d0 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
194e0 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
194f0 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
19500 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
19510 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
19520 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
19530 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
19540 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
19550 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
19560 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
19570 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
19580 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
19590 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
195a0 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
195b0 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
195c0 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
195d0 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
195e0 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
195f0 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
19600 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
19610 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
19620 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
19630 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
19640 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
19650 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
19660 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
19670 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
19680 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
19690 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
196a0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
196b0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
196c0 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
196d0 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
196e0 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
196f0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
19700 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
19710 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
19720 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
19730 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
19740 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
19750 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
19760 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
19770 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
19780 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
19790 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51  t [rowid]..*/.SQ
197a0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
197b0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
197c0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
197d0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
197e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
197f0 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
19800 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
19810 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
19820 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  3.**.** ^This fu
19830 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
19840 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
19850 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65  s modified, inse
19860 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  rted or.** delet
19870 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
19880 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
19890 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
198a0 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
198b0 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64  atement on the d
198c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
198d0 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20  on specified by 
198e0 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
198f0 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e  er..** ^Executin
19900 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65  g any other type
19910 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
19920 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66  t does not modif
19930 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  y the value.** r
19940 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
19950 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
19960 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61  ^Only changes ma
19970 64 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74  de directly by t
19980 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  he INSERT, UPDAT
19990 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
199a0 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e  ement are.** con
199b0 73 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69  sidered - auxili
199c0 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
199d0 65 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52  ed by [CREATE TR
199e0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
199f0 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20  ], .** [foreign 
19a00 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20  key actions] or 
19a10 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
19a20 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  aint resolution 
19a30 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
19a40 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20  .** .** Changes 
19a50 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
19a60 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
19a70 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f  y .** [INSTEAD O
19a80 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54  F trigger | INST
19a90 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d  EAD OF triggers]
19aa0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
19ab0 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a  . ^The value .**
19ac0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
19ad0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
19ae0 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72  mmediately after
19af0 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
19b00 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45  TE or .** DELETE
19b10 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f   statement run o
19b20 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61  n a view is alwa
19b30 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68  ys zero. Only ch
19b40 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65  anges made to re
19b50 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72  al .** tables ar
19b60 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
19b70 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65   Things are more
19b80 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20   complicated if 
19b90 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
19ba0 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ges() function i
19bb0 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68  s.** executed wh
19bc0 69 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72  ile a trigger pr
19bd0 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67  ogram is running
19be0 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65  . This may happe
19bf0 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67  n if the.** prog
19c00 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68  ram uses the [ch
19c10 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
19c20 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d  tion], or if som
19c30 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b  e other callback
19c40 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76  .** function inv
19c50 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61  okes sqlite3_cha
19c60 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e  nges() directly.
19c70 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a   Essentially:.**
19c80 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c   .** <ul>.**   <
19c90 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74  li> ^(Before ent
19ca0 65 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20  ering a trigger 
19cb0 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75  program the valu
19cc0 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  e returned by.**
19cd0 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
19ce0 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
19cf0 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74  on is saved. Aft
19d00 65 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70  er the trigger p
19d10 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20  rogram .**      
19d20 20 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20    has finished, 
19d30 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c  the original val
19d40 75 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29  ue is restored.)
19d50 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ^.** .**   <li> 
19d60 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67  ^(Within a trigg
19d70 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20  er program each 
19d80 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61  INSERT, UPDATE a
19d90 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20  nd DELETE .**   
19da0 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73       statement s
19db0 65 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65  ets the value re
19dc0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
19dd0 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
19de0 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70         upon comp
19df0 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c  letion as normal
19e00 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69  . Of course, thi
19e10 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74  s value will not
19e20 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20   include .**    
19e30 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20      any changes 
19e40 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62  performed by sub
19e50 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68  -triggers, as th
19e60 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
19e70 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76  s() .**        v
19e80 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76  alue will be sav
19e90 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20  ed and restored 
19ea0 61 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74  after each sub-t
19eb0 72 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29  rigger has run.)
19ec0 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a  ^.** </ul>.** .*
19ed0 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68  * ^This means th
19ee0 61 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65  at if the change
19ef0 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
19f00 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73   (or similar) is
19f10 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20   used.** by the 
19f20 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50  first INSERT, UP
19f30 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
19f40 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
19f50 61 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a  a trigger, it .*
19f60 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  * returns the va
19f70 6c 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20  lue as set when 
19f80 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74  the calling stat
19f90 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63  ement began exec
19fa0 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74  uting..** ^If it
19fb0 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
19fc0 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71  second or subseq
19fd0 75 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d  uent such statem
19fe0 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
19ff0 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d  gger .** program
1a000 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
1a010 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68  rned reflects th
1a020 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1a030 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65   modified by the
1a040 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e   .** previous IN
1a050 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1a060 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1a070 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
1a080 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   trigger..**.** 
1a090 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
1a0a0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1a0b0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1a0c0 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
1a0d0 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
1a0e0 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65   and the [change
1a0f0 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1a100 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
1a110 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
1a120 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
1a130 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
1a140 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
1a150 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
1a160 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
1a170 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
1a180 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  ue returned.** i
1a190 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
1a1a0 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
1a1b0 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul..*/.SQLITE_AP
1a1c0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  I int sqlite3_ch
1a1d0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
1a1e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a1f0 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
1a200 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
1a210 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1a220 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
1a230 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1a240 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
1a250 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65   of rows inserte
1a260 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a  d, modified or.*
1a270 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c  * deleted by all
1a280 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
1a290 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
1a2a0 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c  statements compl
1a2b0 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68  eted.** since th
1a2c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a2d0 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64  ction was opened
1a2e0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73  , including thos
1a2f0 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a  e executed as.**
1a300 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72   part of trigger
1a310 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63   programs. ^Exec
1a320 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
1a330 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
1a340 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f  ement.** does no
1a350 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c  t affect the val
1a360 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1a370 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1a380 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e  nges()..** .** ^
1a390 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20  Changes made as 
1a3a0 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e  part of [foreign
1a3b0 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72   key actions] ar
1a3c0 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  e included in th
1a3d0 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20  e.** count, but 
1a3e0 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61  those made as pa
1a3f0 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f  rt of REPLACE co
1a400 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
1a410 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20  ion are.** not. 
1a420 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
1a430 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
1a440 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45  rcepted by INSTE
1a450 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a  AD OF triggers .
1a460 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
1a470 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61  ed..** .** See a
1a480 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
1a490 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
1a4a0 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
1a4b0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
1a4c0 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
1a4d0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
1a4e0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1a4f0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1a500 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1a510 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1a520 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1a530 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1a540 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_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 0a 2a 2a 20 72 65 74 75 72 6e 65 64 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 74  PI int sqlite3_t
1a5c0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
1a5d0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1a5e0 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
1a5f0 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
1a600 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f  g Query.** METHO
1a610 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1a620 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
1a630 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
1a640 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
1a650 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
1a660 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
1a670 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
1a680 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
1a690 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
1a6a0 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
1a6b0 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
1a6c0 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
1a6d0 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
1a6e0 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
1a6f0 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
1a700 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
1a710 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
1a720 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
1a730 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
1a740 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
1a750 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
1a760 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
1a770 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
1a780 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
1a790 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
1a7a0 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
1a7b0 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
1a7c0 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
1a7d0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
1a7e0 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
1a7f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a800 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
1a810 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
1a820 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
1a830 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
1a840 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
1a850 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
1a860 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
1a870 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
1a880 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
1a890 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1a8a0 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
1a8b0 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
1a8c0 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
1a8d0 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
1a8e0 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
1a8f0 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
1a900 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
1a910 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
1a920 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
1a930 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
1a940 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
1a950 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
1a960 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
1a970 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
1a980 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
1a990 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
1a9a0 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
1a9b0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
1a9c0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
1a9d0 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
1a9e0 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
1a9f0 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
1aa00 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
1aa10 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
1aa20 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
1aa30 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
1aa40 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
1aa50 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
1aa60 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
1aa70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1aa80 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
1aa90 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
1aaa0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
1aab0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
1aac0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1aad0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
1aae0 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
1aaf0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
1ab00 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
1ab10 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
1ab20 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
1ab30 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
1ab40 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
1ab50 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1ab60 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
1ab70 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1ab80 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1ab90 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
1aba0 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
1abb0 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
1abc0 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
1abd0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
1abe0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
1abf0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
1ac00 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
1ac10 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
1ac20 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
1ac30 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1ac40 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
1ac50 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
1ac60 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
1ac70 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1ac80 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1ac90 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1aca0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1acb0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
1acc0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
1acd0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
1ace0 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
1acf0 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
1ad00 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
1ad10 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
1ad20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
1ad30 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
1ad40 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
1ad50 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
1ad60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ad70 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
1ad80 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
1ad90 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20   Complete.**.** 
1ada0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1adb0 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67  re useful during
1adc0 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e   command-line in
1add0 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  put to determine
1ade0 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   if the.** curre
1adf0 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78  ntly entered tex
1ae00 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20  t seems to form 
1ae10 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
1ae20 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69  tatement or.** i
1ae30 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
1ae40 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
1ae50 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
1ae60 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  text into.** SQL
1ae70 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
1ae80 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
1ae90 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68  s return 1 if th
1aea0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
1aeb0 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
1aec0 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
1aed0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74  tatement.  ^A st
1aee0 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
1aef0 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
1af00 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
1af10 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
1af20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
1af30 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a   a prefix of a.*
1af40 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52  * well-formed CR
1af50 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
1af60 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f  tement.  ^Semico
1af70 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
1af80 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
1af90 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
1afa0 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
1afb0 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
1afc0 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
1afd0 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
1afe0 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
1aff0 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
1b000 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
1b010 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
1b020 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
1b030 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
1b040 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
1b050 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a  .  ^Whitespace.*
1b060 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74  * and comments t
1b070 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66  hat follow the f
1b080 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61  inal semicolon a
1b090 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  re ignored..**.*
1b0a0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1b0b0 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68  s return 0 if th
1b0c0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69  e statement is i
1b0d0 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20  ncomplete.  ^If 
1b0e0 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
1b0f0 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68  cation fails, th
1b100 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  en SQLITE_NOMEM 
1b110 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1b120 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1b130 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
1b140 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1b150 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20  ts thus.** will 
1b160 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
1b170 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
1b180 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ct SQL..**.** ^(
1b190 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
1b1a0 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
1b1b0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1b1c0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
1b1d0 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
1b1e0 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
1b1f0 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
1b200 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
1b210 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
1b220 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
1b230 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
1b240 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
1b250 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
1b260 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
1b270 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1b280 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
1b290 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
1b2a0 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
1b2b0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
1b2c0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
1b2d0 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
1b2e0 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  mplete.)^.**.** 
1b2f0 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
1b300 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
1b310 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
1b320 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
1b330 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
1b340 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
1b350 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
1b360 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61  e16()] must be a
1b370 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1b380 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
1b390 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
1b3a0 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54   order..*/.SQLIT
1b3b0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1b3c0 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74  3_complete(const
1b3d0 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c   char *sql);.SQL
1b3e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1b3f0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
1b400 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
1b410 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b420 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
1b430 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
1b440 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
1b450 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  rs.** KEYWORDS: 
1b460 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61  {busy-handler ca
1b470 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61  llback} {busy ha
1b480 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  ndler}.** METHOD
1b490 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1b4a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73  ^The sqlite3_bus
1b4b0 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29  y_handler(D,X,P)
1b4c0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1b4d0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1b4e0 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68  n X.** that migh
1b4f0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
1b500 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
1b510 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
1b520 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61  mpt is made to a
1b530 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73 65  ccess a database
1b540 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65   table associate
1b550 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62  d with.** [datab
1b560 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1b570 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74  D when another t
1b580 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63  hread.** or proc
1b590 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62 6c  ess has the tabl
1b5a0 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65  e locked..** The
1b5b0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1b5c0 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63  ndler() interfac
1b5d0 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70  e is used to imp
1b5e0 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74  lement.** [sqlit
1b5f0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1b600 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62  )] and [PRAGMA b
1b610 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a  usy_timeout]..**
1b620 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79  .** ^If the busy
1b630 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1b640 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
1b650 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75  BUSY].** is retu
1b660 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
1b670 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
1b680 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49  ng the lock.  ^I
1b690 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
1b6a0 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  ack.** is not NU
1b6b0 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c  LL, then the cal
1b6c0 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69  lback might be i
1b6d0 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
1b6e0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
1b6f0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
1b700 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79  ment to the busy
1b710 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
1b720 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
1b730 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
1b740 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
1b750 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1b760 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1b770 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  .  ^The second a
1b780 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
1b790 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  e busy handler c
1b7a0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
1b7b0 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74  umber of times t
1b7c0 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e  hat the busy han
1b7d0 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e  dler has.** been
1b7e0 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75   invoked previou
1b7f0 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65  sly for the same
1b800 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
1b810 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79   ^If the.** busy
1b820 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1b830 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64  s 0, then no add
1b840 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73  itional attempts
1b850 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20   are made to.** 
1b860 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
1b870 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ase and [SQLITE_
1b880 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65  BUSY] is returne
1b890 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c  d.** to the appl
1b8a0 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20  ication..** ^If 
1b8b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1b8c0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
1b8d0 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
1b8e0 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
1b8f0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
1b900 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79  abase and the cy
1b910 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
1b920 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
1b930 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
1b940 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
1b950 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c  ntee that it wil
1b960 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
1b970 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
1b980 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e  ck contention. ^
1b990 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
1b9a0 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
1b9b0 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
1b9c0 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
1b9d0 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
1b9e0 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
1b9f0 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
1ba00 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
1ba10 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
1ba20 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  on instead of in
1ba30 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62  voking the .** b
1ba40 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
1ba50 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
1ba60 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
1ba70 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
1ba80 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
1ba90 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
1baa0 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
1bab0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
1bac0 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
1bad0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1bae0 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
1baf0 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
1bb00 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
1bb10 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
1bb20 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
1bb30 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
1bb40 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
1bb50 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1bb60 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
1bb70 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
1bb80 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
1bb90 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
1bba0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
1bbb0 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
1bbc0 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
1bbd0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
1bbe0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
1bbf0 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
1bc00 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
1bc10 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
1bc20 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
1bc30 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
1bc40 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1bc50 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
1bc60 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
1bc70 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
1bc80 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
1bc90 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
1bca0 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
1bcb0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
1bcc0 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
1bcd0 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
1bce0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1bcf0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  L..**.** ^(There
1bd00 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
1bd10 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
1bd20 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
1bd30 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
1bd40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
1bd50 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
1bd60 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
1bd70 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
1bd80 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
1bd90 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
1bda0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
1bdb0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
1bdc0 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20  * or evaluating 
1bdd0 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1bde0 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61  eout=N] will cha
1bdf0 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  nge the.** busy 
1be00 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73  handler and thus
1be10 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69   clear any previ
1be20 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68  ously set busy h
1be30 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
1be40 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
1be50 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
1be60 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
1be70 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
1be80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1be90 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1bea0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1beb0 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  r.  In other wor
1bec0 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20  ds,.** the busy 
1bed0 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72  handler is not r
1bee0 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73  eentrant.  Any s
1bef0 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72  uch actions.** r
1bf00 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
1bf10 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20  ed behavior..** 
1bf20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c  .** A busy handl
1bf30 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
1bf40 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
1bf50 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20  onnection.** or 
1bf60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1bf70 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
1bf80 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1bf90 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  er..*/.SQLITE_AP
1bfa0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  I int sqlite3_bu
1bfb0 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
1bfc0 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a  e3*,int(*)(void*
1bfd0 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f  ,int),void*);../
1bfe0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1bff0 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
1c000 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
1c010 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1c020 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1c030 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1c040 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
1c050 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
1c060 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
1c070 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
1c080 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
1c090 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
1c0a0 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
1c0b0 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
1c0c0 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
1c0d0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1c0e0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1c0f0 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
1c100 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
1c110 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1c120 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1c130 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
1c140 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
1c150 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
1c160 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1c170 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
1c180 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
1c190 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
1c1a0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
1c1b0 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
1c1c0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
1c1d0 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
1c1e0 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
1c1f0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
1c200 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1c210 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1c220 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
1c230 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1c240 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
1c250 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
1c260 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
1c270 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
1c280 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
1c290 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1c2a0 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
1c2b0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
1c2c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
1c2d0 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
1c2e0 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
1c2f0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  d.)^.**.** See a
1c300 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75  lso:  [PRAGMA bu
1c310 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53  sy_timeout].*/.S
1c320 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1c330 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1c340 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
1c350 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
1c360 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
1c370 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
1c380 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a  Running Queries.
1c390 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1c3a0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e3.**.** This is
1c3b0 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66   a legacy interf
1c3c0 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73  ace that is pres
1c3d0 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61  erved for backwa
1c3e0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1c3f0 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69  y..** Use of thi
1c400 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  s interface is n
1c410 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  ot recommended..
1c420 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
1c430 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
1c440 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
1c450 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
1c460 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
1c470 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
1c480 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
1c490 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
1c4a0 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
1c4b0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
1c4c0 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
1c4d0 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
1c4e0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
1c4f0 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
1c500 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
1c510 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
1c520 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
1c530 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
1c540 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
1c550 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
1c560 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
1c570 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
1c580 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
1c590 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
1c5a0 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
1c5b0 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
1c5c0 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
1c5d0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1c5e0 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
1c5f0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
1c600 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1c610 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
1c620 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
1c630 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
1c640 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
1c650 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
1c660 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
1c670 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
1c680 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
1c690 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
1c6a0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
1c6b0 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
1c6c0 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
1c6d0 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
1c6e0 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
1c6f0 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
1c700 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
1c710 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
1c720 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
1c730 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1c740 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
1c750 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
1c760 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
1c770 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
1c780 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1c790 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
1c7a0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
1c7b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1c7c0 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
1c7d0 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
1c7e0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
1c7f0 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
1c800 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
1c810 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
1c820 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
1c830 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1c840 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
1c850 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65  .**.** ^(As an e
1c860 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65  xample of the re
1c870 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61  sult table forma
1c880 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65  t, suppose a que
1c890 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  ry result.** is 
1c8a0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1c8b0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1c8c0 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61  re>.**        Na
1c8d0 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a  me        | Age.
1c8e0 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d  **        ------
1c8f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1c900 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63  -.**        Alic
1c910 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20  e       | 43.** 
1c920 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20         Bob      
1c930 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20     | 28.**      
1c940 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20    Cindy       | 
1c950 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  21.** </pre></bl
1c960 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1c970 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f  There are two co
1c980 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20  lumn (M==2) and 
1c990 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33  three rows (N==3
1c9a0 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20  ).  Thus the.** 
1c9b0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73  result table has
1c9c0 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70   8 entries.  Sup
1c9d0 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20  pose the result 
1c9e0 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a  table is stored.
1c9f0 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e  ** in an array n
1ca00 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20  ames azResult.  
1ca10 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f  Then azResult ho
1ca20 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74  lds this content
1ca30 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1ca40 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1ca50 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1ca60 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a  ;0] = "Name";.**
1ca70 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1ca80 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b  &#91;1] = "Age";
1ca90 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1caa0 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c  ult&#91;2] = "Al
1cab0 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ice";.**        
1cac0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20  azResult&#91;3] 
1cad0 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20  = "43";.**      
1cae0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34    azResult&#91;4
1caf0 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20  ] = "Bob";.**   
1cb00 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1cb10 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20  1;5] = "28";.** 
1cb20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1cb30 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22  #91;6] = "Cindy"
1cb40 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1cb50 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32  sult&#91;7] = "2
1cb60 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  1";.** </pre></b
1cb70 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
1cb80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1cb90 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
1cba0 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
1cbb0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
1cbc0 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
1cbd0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
1cbe0 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
1cbf0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
1cc00 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
1cc10 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
1cc20 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
1cc30 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
1cc40 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
1cc50 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
1cc60 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
1cc70 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
1cc80 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
1cc90 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
1cca0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
1ccb0 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d  table(),.** it m
1ccc0 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73  ust pass the res
1ccd0 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65  ult table pointe
1cce0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
1ccf0 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
1cd00 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65  er to.** release
1cd10 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
1cd20 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20   was malloced.  
1cd30 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
1cd40 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ay the.** [sqlit
1cd50 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
1cd60 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69  pens within sqli
1cd70 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1cd80 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   the calling.** 
1cd90 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  function must no
1cda0 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73  t try to call [s
1cdb0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64  qlite3_free()] d
1cdc0 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a  irectly.  Only.*
1cdd0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
1cde0 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
1cdf0 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
1ce00 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
1ce10 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
1ce20 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
1ce30 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
1ce40 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
1ce50 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
1ce60 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
1ce70 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
1ce80 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1ce90 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
1cea0 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
1ceb0 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
1cec0 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
1ced0 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
1cee0 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
1cef0 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
1cf00 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
1cf10 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
1cf20 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
1cf30 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
1cf40 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
1cf50 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1cf60 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
1cf70 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
1cf80 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
1cf90 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
1cfa0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
1cfb0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
1cfc0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
1cfd0 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  rmsg()]..*/.SQLI
1cfe0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1cff0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
1d000 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1d010 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
1d020 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
1d030 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1d040 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
1d050 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
1d060 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
1d070 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
1d080 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
1d090 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
1d0a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
1d0b0 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
1d0c0 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
1d0d0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
1d0e0 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
1d0f0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
1d100 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
1d110 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
1d120 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
1d130 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
1d140 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53  ten here */.);.S
1d150 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1d160 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1d170 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
1d180 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d190 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
1d1a0 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
1d1b0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1d1c0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1d1d0 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
1d1e0 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
1d1f0 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
1d200 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
1d210 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1d220 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
1d230 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d  nes understand m
1d240 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f  ost of the commo
1d250 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67  n K&R formatting
1d260 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75   options,.** plu
1d270 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  s some additiona
1d280 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66  l non-standard f
1d290 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64  ormats, detailed
1d2a0 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20   below..** Note 
1d2b0 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65  that some of the
1d2c0 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f   more obscure fo
1d2d0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1d2e0 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20   from recent.** 
1d2f0 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61  C-library standa
1d300 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20  rds are omitted 
1d310 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d  from this implem
1d320 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  entation..**.** 
1d330 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1d340 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1d350 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1d360 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1d370 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1d380 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1d390 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1d3a0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1d3b0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1d3c0 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1d3d0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1d3e0 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1d3f0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1d400 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1d410 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1d420 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1d430 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1d440 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1d450 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1d460 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1d470 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1d480 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1d490 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1d4a0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1d4b0 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1d4c0 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1d4d0 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1d4e0 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1d4f0 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1d500 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1d510 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1d520 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1d530 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1d540 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1d550 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1d560 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1d570 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1d580 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1d590 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1d5a0 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1d5b0 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1d5c0 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1d5d0 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1d5e0 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1d5f0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1d600 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1d610 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1d620 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1d630 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1d640 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1d650 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1d660 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1d670 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1d680 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1d690 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1d6a0 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1d6b0 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1d6c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1d6d0 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1d6e0 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1d6f0 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1d700 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1d710 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1d720 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1d730 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1d740 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1d750 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1d760 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1d770 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1d780 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1d790 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1d7a0 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1d7b0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1d7c0 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1d7d0 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1d7e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1d7f0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1d800 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1d810 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1d820 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1d830 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1d840 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1d850 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1d860 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1d870 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1d880 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1d890 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1d8a0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1d8b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1d8c0 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1d8d0 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1d8e0 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1d8f0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1d900 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1d910 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1d920 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1d930 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1d940 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1d950 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1d960 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1d970 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1d980 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1d990 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1d9a0 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1d9b0 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1d9c0 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1d9d0 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20  %q", "%Q", "%w" 
1d9e0 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
1d9f0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
1da00 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1da10 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
1da20 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
1da30 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
1da40 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
1da50 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
1da60 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
1da70 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
1da80 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
1da90 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
1daa0 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
1dab0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
1dac0 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
1dad0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
1dae0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
1daf0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
1db00 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
1db10 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
1db20 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
1db30 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1db40 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
1db50 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
1db60 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
1db70 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1db80 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1db90 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1dba0 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
1dbb0 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
1dbc0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1dbd0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
1dbe0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
1dbf0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1dc00 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
1dc10 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1dc20 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1dc30 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1dc40 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1dc50 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1dc60 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
1dc70 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1dc80 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1dc90 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1dca0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1dcb0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1dcc0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
1dcd0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
1dce0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
1dcf0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
1dd00 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
1dd10 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
1dd20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
1dd30 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
1dd40 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1dd50 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1dd60 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1dd70 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
1dd80 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
1dd90 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1dda0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
1ddb0 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
1ddc0 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
1ddd0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
1dde0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
1ddf0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
1de00 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1de10 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1de20 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1de30 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1de40 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
1de50 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
1de60 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1de70 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
1de80 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
1de90 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
1dea0 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
1deb0 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
1dec0 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
1ded0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
1dee0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
1def0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
1df00 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
1df10 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
1df20 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
1df30 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
1df40 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
1df50 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
1df60 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
1df70 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
1df80 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
1df90 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1dfa0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
1dfb0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
1dfc0 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
1dfd0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
1dfe0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
1dff0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
1e000 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
1e010 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
1e020 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
1e030 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1e040 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1e050 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1e060 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1e070 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
1e080 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1e090 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1e0a0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1e0b0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1e0c0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1e0d0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1e0e0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
1e0f0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
1e100 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
1e110 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
1e120 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
1e130 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
1e140 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
1e150 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
1e160 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1e170 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b  ng option is lik
1e180 65 20 22 25 71 22 20 65 78 63 65 70 74 20 74 68  e "%q" except th
1e190 61 74 20 69 74 20 65 78 70 65 63 74 73 20 74 6f  at it expects to
1e1a0 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  .** be contained
1e1b0 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71   within double-q
1e1c0 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66  uotes instead of
1e1d0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20   single quotes, 
1e1e0 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65  and it.** escape
1e1f0 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f  s the double-quo
1e200 74 65 20 63 68 61 72 61 63 74 65 72 20 69 6e 73  te character ins
1e210 74 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67  tead of the sing
1e220 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72  le-quote.** char
1e230 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25  acter.)^  The "%
1e240 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  w" formatting op
1e250 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64  tion is intended
1e260 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65   for safely inse
1e270 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61  rting.** table a
1e280 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20  nd column names 
1e290 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74  into a construct
1e2a0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1e2b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1e2c0 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
1e2d0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1e2e0 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
1e2f0 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
1e300 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
1e310 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
1e320 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
1e330 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
1e340 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1e350 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
1e360 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
1e370 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )^.*/.SQLITE_API
1e380 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d   char *sqlite3_m
1e390 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1e3a0 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f  r*,...);.SQLITE_
1e3b0 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
1e3c0 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
1e3d0 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1e3e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1e3f0 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
1e400 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1e410 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
1e420 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1e430 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69   *sqlite3_vsnpri
1e440 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1e450 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1e460 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  st);../*.** CAPI
1e470 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
1e480 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
1e490 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
1e4a0 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
1e4b0 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
1e4c0 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
1e4d0 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
1e4e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1e4f0 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
1e500 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
1e510 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
1e520 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
1e530 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
1e540 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
1e550 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
1e560 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
1e570 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
1e580 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1e590 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
1e5a0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
1e5b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e5c0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1e5d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1e5e0 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
1e5f0 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
1e600 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
1e610 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
1e620 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
1e630 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e640 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
1e650 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
1e660 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
1e670 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
1e680 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
1e690 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
1e6a0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
1e6b0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
1e6c0 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
1e6d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e6e0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
1e6f0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1e700 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1e710 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74 69  alloc64(N) routi
1e720 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69  ne works just li
1e730 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ke.** sqlite3_ma
1e740 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20 74  lloc(N) except t
1e750 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73 69  hat N is an unsi
1e760 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74 65  gned 64-bit inte
1e770 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
1e780 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62 69  f a signed 32-bi
1e790 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
1e7a0 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
1e7b0 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20  3_free() with a 
1e7c0 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73  pointer previous
1e7d0 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ly returned.** b
1e7e0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1e7f0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1e800 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73  alloc() releases
1e810 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a   that memory so.
1e820 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  ** that it might
1e830 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68   be reused.  ^Th
1e840 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  e sqlite3_free()
1e850 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61   routine is.** a
1e860 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c   no-op if is cal
1e870 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
1e880 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e  pointer.  Passin
1e890 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  g a NULL pointer
1e8a0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  .** to sqlite3_f
1e8b0 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73  ree() is harmles
1e8c0 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20  s.  After being 
1e8d0 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a  freed, memory.**
1e8e0 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20   should neither 
1e8f0 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74  be read nor writ
1e900 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69  ten.  Even readi
1e910 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72  ng previously fr
1e920 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69  eed.** memory mi
1e930 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20  ght result in a 
1e940 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
1e950 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  lt or other seve
1e960 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d  re error..** Mem
1e970 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20  ory corruption, 
1e980 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1e990 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73  ault, or other s
1e9a0 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  evere error.** m
1e9b0 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73  ight result if s
1e9c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1e9d0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e   called with a n
1e9e0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  on-NULL pointer 
1e9f0 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  that.** was not 
1ea00 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
1ea10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1ea20 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1ea30 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  c()..**.** ^The 
1ea40 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ea50 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 61  X,N) interface a
1ea60 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
1ea70 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
1ea80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58  ory allocation X
1ea90 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
1eaa0 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  N bytes..** ^If 
1eab0 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20  the X parameter 
1eac0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1ead0 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20  oc(X,N).** is a 
1eae0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1eaf0 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
1eb00 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
1eb10 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1eb20 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20  3_malloc(N)..** 
1eb30 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65  ^If the N parame
1eb40 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1eb50 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a  ealloc(X,N) is z
1eb60 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
1eb70 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
1eb80 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
1eb90 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
1eba0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
1ebb0 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69  ree(X)..** ^sqli
1ebc0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1ebd0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1ebe0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
1ebf0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
1ec00 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1ec10 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
1ec20 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74   if insufficient
1ec30 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69 6c   memory is avail
1ec40 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69  able..** ^If M i
1ec50 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
1ec60 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1ec70 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
1ec80 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
1ec90 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1eca0 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
1ecb0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
1ecc0 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
1ecd0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1ece0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61  3_realloc(X,N) a
1ecf0 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
1ed00 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
1ed10 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1ed20 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65  _realloc(X,N) re
1ed30 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e  turns NULL and N
1ed40 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68   is positive, th
1ed50 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20  en the.** prior 
1ed60 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f  allocation is no
1ed70 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  t freed..**.** ^
1ed80 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1ed90 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65 72  loc64(X,N) inter
1eda0 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65 20  faces works the 
1edb0 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74  same as.** sqlit
1edc0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1edd0 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73  except that N is
1ede0 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e   a 64-bit unsign
1edf0 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65  ed integer inste
1ee00 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69  ad.** of a 32-bi
1ee10 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
1ee20 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73  ..**.** ^If X is
1ee30 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1ee40 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79 20  tion previously 
1ee50 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
1ee60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a  lite3_malloc(),.
1ee70 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1ee80 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  c64(), sqlite3_r
1ee90 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c  ealloc(), or sql
1eea0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29  ite3_realloc64()
1eeb0 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
1eec0 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
1eed0 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  ns the size of t
1eee0 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hat memory alloc
1eef0 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a  ation in bytes..
1ef00 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  ** ^The value re
1ef10 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1ef20 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68 74  3_msize(X) might
1ef30 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
1ef40 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66  the number.** of
1ef50 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65 64   bytes requested
1ef60 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f   when X was allo
1ef70 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69 73  cated.  ^If X is
1ef80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1ef90 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
1efa0 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73  msize(X) returns
1efb0 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f 69   zero.  If X poi
1efc0 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67  nts to something
1efd0 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20   that is not.** 
1efe0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
1eff0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1f000 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f 69  on, or if it poi
1f010 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c  nts to a formerl
1f020 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72  y.** valid memor
1f030 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61  y allocation tha
1f040 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20 66  t has now been f
1f050 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62  reed, then the b
1f060 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71  ehavior.** of sq
1f070 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 69  lite3_msize(X) i
1f080 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
1f090 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75 6c  possibly harmful
1f0a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1f0b0 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
1f0c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f0d0 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
1f0e0 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c(),.** sqlite3_
1f0f0 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20  malloc64(), and 
1f100 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1f110 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  4().** is always
1f120 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
1f130 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
1f140 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61  oundary, or to a
1f150 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64  .** 4 byte bound
1f160 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49  ary if the [SQLI
1f170 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45  TE_4_BYTE_ALIGNE
1f180 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c  D_MALLOC] compil
1f190 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
1f1a0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1f1b0 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
1f1c0 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
1f1d0 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
1f1e0 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
1f1f0 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
1f200 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
1f210 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
1f220 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
1f230 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
1f240 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
1f250 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
1f260 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
1f270 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
1f280 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
1f290 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
1f2a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
1f2b0 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
1f2c0 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69  ** Prior to SQLi
1f2d0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31  te version 3.7.1
1f2e0 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f  0, the Windows O
1f2f0 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
1f300 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20  r called.** the 
1f310 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
1f320 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
1f330 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
1f340 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
1f350 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
1f360 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
1f370 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
1f380 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
1f390 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
1f3a0 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
1f3b0 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
1f3c0 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
1f3d0 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
1f3e0 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64  on errors were d
1f3f0 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
1f400 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74  they were report
1f410 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
1f420 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
1f430 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
1f440 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
1f450 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
1f460 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
1f470 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
1f480 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
1f490 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1f4a0 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
1f4b0 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
1f4c0 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
1f4d0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
1f4e0 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
1f4f0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1f500 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
1f510 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
1f520 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
1f530 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
1f540 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
1f550 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
1f560 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
1f570 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
1f580 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
1f590 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
1f5a0 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
1f5b0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
1f5c0 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
1f5d0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
1f5e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1f5f0 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
1f600 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  (int);.SQLITE_AP
1f610 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
1f620 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33  malloc64(sqlite3
1f630 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45  _uint64);.SQLITE
1f640 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
1f650 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
1f660 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
1f670 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
1f680 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a  _realloc64(void*
1f690 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
1f6a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1f6b0 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
1f6c0 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  void*);.SQLITE_A
1f6d0 50 49 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  PI sqlite3_uint6
1f6e0 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  4 sqlite3_msize(
1f6f0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1f700 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1f710 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
1f720 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
1f730 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
1f740 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
1f750 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
1f760 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
1f770 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
1f780 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
1f790 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
1f7a0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1f7b0 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
1f7c0 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
1f7d0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1f7e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
1f7f0 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
1f800 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1f810 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
1f820 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1f830 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
1f840 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
1f850 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
1f860 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
1f870 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
1f880 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1f890 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
1f8a0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1f8b0 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
1f8c0 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
1f8d0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
1f8e0 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
1f8f0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
1f900 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
1f910 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
1f920 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
1f930 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
1f940 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1f950 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1f960 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
1f970 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
1f980 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
1f990 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1f9a0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1f9b0 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
1f9c0 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
1f9d0 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
1f9e0 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
1f9f0 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
1fa00 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
1fa10 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
1fa20 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
1fa30 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
1fa40 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
1fa50 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
1fa60 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
1fa70 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1fa80 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
1fa90 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
1faa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1fab0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1fac0 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
1fad0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
1fae0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
1faf0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
1fb00 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
1fb10 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
1fb20 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
1fb30 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  .*/.SQLITE_API s
1fb40 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1fb50 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1fb60 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
1fb70 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
1fb80 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1fb90 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
1fba0 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
1fbb0 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
1fbc0 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
1fbd0 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
1fbe0 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
1fbf0 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
1fc00 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
1fc10 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
1fc20 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
1fc30 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
1fc40 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
1fc50 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
1fc60 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
1fc70 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
1fc80 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
1fc90 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
1fca0 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
1fcb0 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
1fcc0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
1fcd0 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
1fce0 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
1fcf0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
1fd00 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
1fd10 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
1fd20 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
1fd30 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
1fd40 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
1fd50 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
1fd60 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
1fd70 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
1fd80 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
1fd90 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54   buffer P..** ^T
1fda0 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63  he P parameter c
1fdb0 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  an be a NULL poi
1fdc0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  nter..**.** ^If 
1fdd0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73  this routine has
1fde0 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f   not been previo
1fdf0 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69  usly called or i
1fe00 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a  f the previous.*
1fe10 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73  * call had N les
1fe20 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20  s than one or a 
1fe30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
1fe40 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e   P, then the PRN
1fe50 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75  G is.** seeded u
1fe60 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20  sing randomness 
1fe70 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68  obtained from th
1fe80 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
1fe90 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64  thod of.** the d
1fea0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1feb0 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  vfs] object..** 
1fec0 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73  ^If the previous
1fed0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
1fee0 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f  utine had an N o
1fef0 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20  f 1 or more and 
1ff00 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20  a.** non-NULL P 
1ff10 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d  then the pseudo-
1ff20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
1ff30 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
1ff40 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
1ff50 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
1ff60 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
1ff70 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
1ff80 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ethod..*/.SQLITE
1ff90 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
1ffa0 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
1ffb0 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
1ffc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1ffd0 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
1ffe0 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
1fff0 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  cks.** METHOD: s
20000 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
20010 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
20020 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a  ters an authoriz
20030 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
20040 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
20050 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
20060 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
20070 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
20080 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
20090 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
200a0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
200b0 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
200c0 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
200d0 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
200e0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
200f0 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
20100 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20110 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
20120 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
20130 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
20140 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
20150 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
20160 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
20170 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
20180 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
20190 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
201a0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
201b0 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
201c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
201d0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
201e0 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
201f0 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
20200 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
20210 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20220 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
20230 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
20240 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
20250 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
20260 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
20270 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
20280 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
20290 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
202a0 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
202b0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
202c0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
202d0 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
202e0 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
202f0 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
20300 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
20310 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
20320 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20330 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
20340 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
20350 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
20360 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
20370 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
20380 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
20390 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
203a0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
203b0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
203c0 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
203d0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
203e0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
203f0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
20400 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
20410 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
20420 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
20430 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
20440 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
20450 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
20460 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
20470 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
20480 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
20490 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
204a0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
204b0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
204c0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
204d0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
204e0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
204f0 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
20500 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
20510 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
20520 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
20530 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
20540 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
20550 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
20560 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
20570 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
20580 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
20590 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
205a0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
205b0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
205c0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
205d0 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
205e0 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
205f0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
20600 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
20610 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
20620 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
20630 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
20640 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
20650 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
20660 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
20670 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
20680 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
20690 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
206a0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
206b0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
206c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
206d0 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
206e0 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
206f0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
20700 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
20710 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
20720 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
20730 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
20740 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
20750 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
20760 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
20770 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
20780 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
20790 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
207a0 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
207b0 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
207c0 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
207d0 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
207e0 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
207f0 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
20800 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
20810 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
20820 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
20830 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
20840 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
20850 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
20860 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
20870 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
20880 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
20890 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
208a0 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
208b0 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
208c0 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
208d0 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
208e0 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
208f0 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
20900 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
20910 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
20920 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
20930 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20940 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
20950 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
20960 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
20970 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
20980 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
20990 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
209a0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
209b0 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
209c0 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
209d0 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
209e0 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
209f0 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
20a00 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
20a10 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
20a20 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
20a30 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
20a40 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
20a50 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
20a60 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
20a70 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
20a80 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
20a90 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
20aa0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
20ab0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
20ac0 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
20ad0 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
20ae0 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
20af0 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
20b00 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
20b10 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
20b20 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
20b30 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
20b40 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
20b50 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
20b60 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
20b70 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
20b80 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
20b90 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
20ba0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
20bb0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
20bc0 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
20bd0 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
20be0 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
20bf0 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
20c00 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
20c10 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
20c20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
20c30 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
20c40 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
20c50 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
20c60 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
20c70 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
20c80 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
20c90 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
20ca0 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
20cb0 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
20cc0 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
20cd0 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
20ce0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
20cf0 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
20d00 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
20d10 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
20d20 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
20d30 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
20d40 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
20d50 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
20d60 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
20d70 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
20d80 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
20d90 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
20da0 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
20db0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
20dc0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
20dd0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
20de0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
20df0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
20e00 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
20e10 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20e20 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
20e30 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
20e40 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
20e50 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
20e60 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
20e70 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
20e80 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
20e90 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
20ea0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
20eb0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
20ec0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
20ed0 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
20ee0 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
20ef0 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
20f00 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
20f10 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
20f20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
20f30 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
20f40 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
20f50 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
20f60 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
20f70 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
20f80 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
20f90 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20fa0 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
20fb0 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
20fc0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
20fd0 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
20fe0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20ff0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
21000 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
21010 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
21020 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
21030 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
21040 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
21050 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
21060 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
21070 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
21080 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
21090 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
210a0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
210b0 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
210c0 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
210d0 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
210e0 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
210f0 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
21100 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
21110 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c  a change..*/.SQL
21120 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
21130 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
21140 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
21150 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
21160 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
21170 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
21180 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
21190 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
211a0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
211b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
211c0 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
211d0 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
211e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
211f0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
21200 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21210 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
21220 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
21230 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
21240 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
21250 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
21260 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
21270 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
21280 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
21290 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
212a0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
212b0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
212c0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
212d0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
212e0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
212f0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
21300 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
21310 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20  QLITE_IGNORE is 
21320 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b  also used as a [
21330 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74  conflict resolut
21340 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74  ion mode].** ret
21350 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b  urned from the [
21360 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f  sqlite3_vtab_on_
21370 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65  conflict()] inte
21380 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  rface..*/.#defin
21390 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
213a0 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
213b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
213c0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
213d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
213e0 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
213f0 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
21400 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
21410 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
21420 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21430 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
21440 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
21450 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
21460 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
21470 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
21480 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
21490 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
214a0 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
214b0 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51  orize certain SQ
214c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
214d0 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
214e0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
214f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
21500 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
21510 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
21520 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
21530 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
21540 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
21550 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
21560 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
21570 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
21580 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
21590 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
215a0 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
215b0 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
215c0 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
215d0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a  tion is to be.**
215e0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
215f0 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
21600 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
21610 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
21620 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
21630 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
21640 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
21650 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
21660 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
21670 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
21680 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
21690 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70  er.  ^(The 5th p
216a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
216b0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
216c0 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
216d0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
216e0 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
216f0 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
21700 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e  applicable.)^  ^
21710 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
21720 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
21730 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
21740 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
21750 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
21760 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
21770 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
21780 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
21790 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
217a0 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
217b0 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
217c0 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74  rectly from.** t
217d0 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
217e0 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
217f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21800 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21810 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
21820 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
21830 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
21840 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
21850 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
21860 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
21870 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21880 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21890 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
218a0 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
218b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
218c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
218d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
218e0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
218f0 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
21900 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
21910 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
21920 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21930 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
21940 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
21950 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
21960 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21970 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21980 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
21990 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
219a0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
219b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
219c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
219d0 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
219e0 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
219f0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
21a00 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21a10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
21a20 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
21a30 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
21a40 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
21a50 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
21a60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
21a70 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
21a80 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
21a90 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
21aa0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21ab0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
21ac0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
21ad0 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
21ae0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
21af0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21b00 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
21b10 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
21b20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
21b30 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
21b40 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
21b50 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
21b60 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
21b70 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
21b80 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
21b90 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21ba0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
21bb0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
21bc0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
21bd0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
21be0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21bf0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
21c00 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
21c10 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
21c20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21c30 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21c40 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
21c50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
21c60 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
21c70 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
21c80 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21c90 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
21ca0 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
21cb0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
21cc0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21cd0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21ce0 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
21cf0 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
21d00 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
21d10 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
21d20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21d30 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
21d40 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
21d50 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
21d60 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21d70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21d80 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
21d90 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
21da0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21db0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21dc0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21dd0 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
21de0 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
21df0 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
21e00 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
21e10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21e20 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
21e30 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
21e40 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
21e50 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
21e60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21e70 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
21e80 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
21e90 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
21ea0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21eb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
21ec0 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
21ed0 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
21ee0 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
21ef0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21f00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
21f10 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
21f20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
21f30 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
21f40 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
21f50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
21f60 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
21f70 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
21f80 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
21f90 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21fa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
21fb0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
21fc0 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
21fd0 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
21fe0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21ff0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
22000 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
22010 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
22020 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
22030 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22040 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
22050 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
22060 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
22070 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
22080 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22090 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
220a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
220b0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
220c0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
220d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
220e0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
220f0 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
22100 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22110 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
22120 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22130 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
22140 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
22150 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22160 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
22170 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22180 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
22190 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
221a0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
221b0 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
221c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
221d0 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
221e0 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
221f0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
22200 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
22210 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22220 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
22230 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
22240 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
22250 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22260 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20  E_RECURSIVE     
22270 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e         33   /* N
22280 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
22290 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
222a0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
222b0 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
222c0 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
222d0 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
222e0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73  lite3.**.** Thes
222f0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
22300 65 70 72 65 63 61 74 65 64 2e 20 55 73 65 20 74  eprecated. Use t
22310 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  he [sqlite3_trac
22320 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  e_v2()] interfac
22330 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66 20  e.** instead of 
22340 74 68 65 20 72 6f 75 74 69 6e 65 73 20 64 65 73  the routines des
22350 63 72 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  cribed here..**.
22360 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
22370 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
22380 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
22390 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
223a0 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
223b0 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
223c0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
223d0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
223e0 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
223f0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
22400 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
22410 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
22420 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
22430 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
22440 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
22450 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
22460 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
22470 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
22480 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
22490 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
224a0 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
224b0 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
224c0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
224d0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
224e0 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
224f0 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
22500 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
22510 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
22520 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
22530 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
22540 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
22550 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
22560 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
22570 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
22580 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
22590 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
225a0 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
225b0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  .)^.**.** The [S
225c0 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45  QLITE_TRACE_SIZE
225d0 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d  _LIMIT] compile-
225e0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20  time option can 
225f0 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74  be used to limit
22600 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  .** the length o
22610 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  f [bound paramet
22620 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e  er] expansion in
22630 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73   the output of s
22640 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a  qlite3_trace()..
22650 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
22660 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
22670 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
22680 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
22690 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
226a0 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
226b0 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
226c0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
226d0 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
226e0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
226f0 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
22700 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
22710 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
22720 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
22730 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
22740 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
22750 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
22760 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
22770 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
22780 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
22790 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
227a0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
227b0 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
227c0 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
227d0 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
227e0 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
227f0 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
22800 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
22810 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
22820 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
22830 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
22840 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
22850 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
22860 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
22870 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
22880 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
22890 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
228a0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
228b0 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
228c0 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
228d0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
228e0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54  SQLite..*/.SQLIT
228f0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
22900 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71  RECATED void *sq
22910 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
22920 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
22930 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
22940 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
22950 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
22960 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
22970 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
22980 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
22990 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
229a0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
229b0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
229c0 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
229d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
229e0 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 43  QL Trace Event C
229f0 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
22a00 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a  : SQLITE_TRACE.*
22a10 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
22a20 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c  ants identify cl
22a30 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20  asses of events 
22a40 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69  that can be moni
22a50 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74  tored.** using t
22a60 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  he [sqlite3_trac
22a70 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20  e_v2()] tracing 
22a80 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68 69 72  logic.  The thir
22a90 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  d argument.** to
22aa0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
22ab0 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65  v2()] is an OR-e
22ac0 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  d combination of
22ad0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a   one or more of.
22ae0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
22af0 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68   constants.  ^Th
22b00 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
22b10 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
22b20 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65  llback.** is one
22b30 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
22b40 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a  g constants..**.
22b50 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63  ** New tracing c
22b60 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20  onstants may be 
22b70 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
22b80 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
22b90 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ^A trace callbac
22ba0 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d  k has four argum
22bb0 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28  ents: xCallback(
22bc0 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68  T,C,P,X)..** ^Th
22bd0 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e T argument is 
22be0 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67  one of the integ
22bf0 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 61 62  er type codes ab
22c00 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61  ove..** ^The C a
22c10 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70  rgument is a cop
22c20 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74  y of the context
22c30 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
22c40 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  in as the.** fou
22c50 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
22c60 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
22c70 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61  2()]..** The P a
22c80 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61  nd X arguments a
22c90 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73  re pointers whos
22ca0 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e  e meanings depen
22cb0 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64  d on T..**.** <d
22cc0 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  l>.** [[SQLITE_T
22cd0 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e  RACE_STMT]] <dt>
22ce0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
22cf0 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  T</dt>.** <dd>^A
22d00 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  n SQLITE_TRACE_S
22d10 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  TMT callback is 
22d20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70  invoked when a p
22d30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22d40 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e  t.** first begin
22d50 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f  s running and po
22d60 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20  ssibly at other 
22d70 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65  times during the
22d80 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  .** execution of
22d90 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
22da0 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73  atement, such as
22db0 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f 66   at the start of
22dc0 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72   each.** trigger
22dd0 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68   subprogram. ^Th
22de0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
22df0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
22e00 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
22e10 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58  atement]. ^The X
22e20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
22e30 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
22e40 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  ng which.** is t
22e50 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51  he unexpanded SQ
22e60 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 72  L text of the pr
22e70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22e80 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65   or an SQL comme
22e90 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  nt .** that indi
22ea0 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61  cates the invoca
22eb0 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65  tion of a trigge
22ec0 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  r.  ^The callbac
22ed0 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a  k can compute.**
22ee0 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 20 74   the same text t
22ef0 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62  hat would have b
22f00 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  een returned by 
22f10 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
22f20 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20  te3_trace()].** 
22f30 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 73 69  interface by usi
22f40 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e  ng the X argumen
22f50 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20  t when X begins 
22f60 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e  with "--" and in
22f70 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  voking.** [sqlit
22f80 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
22f90 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  P)] otherwise..*
22fa0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
22fb0 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64  ACE_PROFILE]] <d
22fc0 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  t>SQLITE_TRACE_P
22fd0 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ROFILE</dt>.** <
22fe0 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
22ff0 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c  ACE_PROFILE call
23000 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70  back provides ap
23010 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20  proximately the 
23020 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  same.** informat
23030 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64  ion as is provid
23040 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
23050 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61  e3_profile()] ca
23060 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
23070 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
23080 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
23090 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
230a0 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58  nt] and the.** X
230b0 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
230c0 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74   to a 64-bit int
230d0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74 68  eger which is th
230e0 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a  e estimated of.*
230f0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
23100 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20  nanosecond that 
23110 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
23120 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
23130 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  un..** ^The SQLI
23140 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
23150 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
23160 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73 74  oked when the st
23170 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
23180 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
23190 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74  _TRACE_ROW]] <dt
231a0 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f  >SQLITE_TRACE_RO
231b0 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  W</dt>.** <dd>^A
231c0 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  n SQLITE_TRACE_R
231d0 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  OW callback is i
231e0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
231f0 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
23200 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65  atement generate
23210 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  s a single row o
23220 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e  f result.  .** ^
23230 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
23240 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
23250 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
23260 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a  tement] and the.
23270 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  ** X argument is
23280 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   unused..**.** [
23290 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c  [SQLITE_TRACE_CL
232a0 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  OSE]] <dt>SQLITE
232b0 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74  _TRACE_CLOSE</dt
232c0 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
232d0 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20  ITE_TRACE_CLOSE 
232e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
232f0 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74 61 62  ked when a datab
23300 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
23310 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68  n closes..** ^Th
23320 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
23330 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
23340 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
23350 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a  ction] object.**
23360 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d   and the X argum
23370 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a  ent is unused..*
23380 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
23390 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
233a0 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a  STMT       0x01.
233b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
233c0 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20  RACE_PROFILE    
233d0 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x02.#define SQL
233e0 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20  ITE_TRACE_ROW   
233f0 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e       0x04.#defin
23400 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  e SQLITE_TRACE_C
23410 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a  LOSE      0x08..
23420 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23430 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a  SQL Trace Hook.*
23440 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
23450 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
23460 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c  ite3_trace_v2(D,
23470 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  M,X,P) interface
23480 20 72 65 67 69 73 74 65 72 73 20 61 20 74 72 61   registers a tra
23490 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  ce callback.** f
234a0 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73  unction X agains
234b0 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  t [database conn
234c0 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67  ection] D, using
234d0 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d   property mask M
234e0 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20  .** and context 
234f0 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20  pointer P.  ^If 
23500 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  the X callback i
23510 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20  s.** NULL or if 
23520 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65  the M mask is ze
23530 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67  ro, then tracing
23540 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54   is disabled.  T
23550 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74  he.** M argument
23560 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62   should be the b
23570 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d  itwise OR-ed com
23580 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a  bination of.** z
23590 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c  ero or more [SQL
235a0 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74  ITE_TRACE] const
235b0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  ants..**.** ^Eac
235c0 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  h call to either
235d0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
235e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63   or sqlite3_trac
235f0 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65 73  e_v2() overrides
23600 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61   .** (cancels) a
23610 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74  ny prior calls t
23620 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  o sqlite3_trace(
23630 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ) or sqlite3_tra
23640 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  ce_v2()..**.** ^
23650 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  The X callback i
23660 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  s invoked whenev
23670 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76  er any of the ev
23680 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64 20  ents identified 
23690 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63  by .** mask M oc
236a0 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67  cur.  ^The integ
236b0 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  er return value 
236c0 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63  from the callbac
236d0 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a  k is currently.*
236e0 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67  * ignored, thoug
236f0 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67  h this may chang
23700 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  e in future rele
23710 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a  ases.  Callback.
23720 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
23730 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ns should return
23740 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20   zero to ensure 
23750 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69  future compatibi
23760 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74  lity..**.** ^A t
23770 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  race callback is
23780 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f   invoked with fo
23790 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61  ur arguments: ca
237a0 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e  llback(T,C,P,X).
237b0 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d  .** ^The T argum
237c0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ent is one of th
237d0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d  e [SQLITE_TRACE]
237e0 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f  .** constants to
237f0 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 74 68   indicate why th
23800 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69  e callback was i
23810 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  nvoked..** ^The 
23820 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  C argument is a 
23830 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
23840 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ext pointer..** 
23850 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75  The P and X argu
23860 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65  ments are pointe
23870 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67  rs whose meaning
23880 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a  s depend on T..*
23890 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
238a0 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65  _trace_v2() inte
238b0 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65  rface is intende
238c0 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65  d to replace the
238d0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
238e0 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74  faces [sqlite3_t
238f0 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  race()] and [sql
23900 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c  ite3_profile()],
23910 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a   both of which.*
23920 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64  * are deprecated
23930 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
23940 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 63  int sqlite3_trac
23950 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  e_v2(.  sqlite3*
23960 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d 61  ,.  unsigned uMa
23970 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c  sk,.  int(*xCall
23980 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76  back)(unsigned,v
23990 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a  oid*,void*,void*
239a0 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78 0a  ),.  void *pCtx.
239b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
239c0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
239d0 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  ss Callbacks.** 
239e0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
239f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
23a00 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
23a10 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
23a20 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
23a30 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
23a40 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
23a50 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
23a60 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
23a70 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
23a80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
23a90 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
23aa0 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
23ab0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
23ac0 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
23ad0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
23ae0 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
23af0 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
23b00 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
23b10 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
23b20 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
23b30 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
23b40 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
23b50 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
23b60 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
23b70 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
23b80 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
23b90 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
23ba0 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72  er N is the appr
23bb0 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f  oximate number o
23bc0 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
23bd0 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
23be0 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
23bf0 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
23c00 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
23c10 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
23c20 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49   callback X.  ^I
23c30 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
23c40 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72   one then the pr
23c50 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65  ogress.** handle
23c60 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  r is disabled..*
23c70 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
23c80 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
23c90 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
23ca0 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
23cb0 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
23cc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
23cd0 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
23ce0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
23cf0 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
23d00 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
23d10 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
23d20 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
23d30 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
23d40 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
23d50 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
23d60 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
23d70 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
23d80 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
23d90 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
23da0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
23db0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
23dc0 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
23dd0 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
23de0 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
23df0 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
23e00 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
23e10 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
23e20 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
23e30 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
23e40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
23e50 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
23e60 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
23e70 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
23e80 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
23e90 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
23ea0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
23eb0 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
23ec0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
23ed0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
23ee0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
23ef0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23f00 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
23f10 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
23f20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
23f30 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
23f40 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
23f50 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
23f60 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
23f70 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
23f80 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
23f90 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
23fa0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
23fb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23fc0 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
23fd0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
23fe0 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f  on.** CONSTRUCTO
23ff0 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
24000 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
24010 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
24020 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73  database file as
24030 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
24040 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  e .** filename a
24050 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69  rgument. ^The fi
24060 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
24070 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
24080 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
24090 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
240a0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
240b0 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
240c0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
240d0 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
240e0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
240f0 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73  (). ^(A [databas
24100 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
24110 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
24120 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
24130 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
24140 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
24150 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
24160 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
24170 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
24180 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
24190 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
241a0 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
241b0 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
241c0 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
241d0 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
241e0 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
241f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
24200 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20   object.)^ ^(If 
24210 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
24220 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
24230 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
24240 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
24250 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
24260 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
24270 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
24280 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
24290 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   ^The.** [sqlite
242a0 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
242b0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
242c0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
242d0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
242e0 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
242f0 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
24300 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
24310 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  or following a f
24320 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a  ailure of any.**
24330 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
24340 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e  open() routines.
24350 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
24360 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c  ult encoding wil
24370 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64  l be UTF-8 for d
24380 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64  atabases created
24390 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65   using.** sqlite
243a0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
243b0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
243c0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
243d0 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61  oding for databa
243e0 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75  ses.** created u
243f0 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  sing sqlite3_ope
24400 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54  n16() will be UT
24410 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
24420 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
24430 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
24440 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
24450 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
24460 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
24470 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
24480 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
24490 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
244a0 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
244b0 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
244c0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
244d0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
244e0 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
244f0 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
24500 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
24510 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
24520 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
24530 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
24540 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
24550 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
24560 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
24570 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
24580 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
24590 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
245a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
245b0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
245c0 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
245d0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
245e0 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
245f0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
24600 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
24610 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
24620 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
24630 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
24640 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
24650 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
24660 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
24670 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ACHE],.** [SQLIT
24680 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
24690 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51  CHE], and/or [SQ
246a0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
246b0 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
246c0 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
246d0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
246e0 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
246f0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
24700 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
24710 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
24720 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
24730 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
24740 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
24750 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
24760 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
24770 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
24780 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
24790 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
247a0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
247b0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
247c0 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
247d0 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
247e0 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
247f0 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
24800 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
24810 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
24820 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
24830 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
24840 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
24850 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
24860 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
24870 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
24880 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
24890 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
248a0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
248b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
248c0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
248d0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
248e0 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
248f0 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
24900 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
24910 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
24920 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
24930 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
24940 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
24950 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
24960 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
24970 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
24980 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
24990 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
249a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
249b0 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
249c0 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
249d0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70  s shown above op
249e0 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
249f0 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20  d with other.** 
24a00 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
24a10 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f  DONLY | SQLITE_O
24a20 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74  PEN_* bits].** t
24a30 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
24a40 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
24a50 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
24a60 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
24a70 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
24a80 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
24a90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
24aa0 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
24ab0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
24ac0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
24ad0 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
24ae0 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
24af0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
24b00 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
24b10 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
24b20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
24b30 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
24b40 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
24b50 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
24b60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
24b70 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
24b80 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
24b90 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
24ba0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
24bb0 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
24bc0 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
24bd0 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
24be0 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
24bf0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
24c00 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
24c10 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
24c20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
24c30 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
24c40 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
24c50 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
24c60 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
24c70 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
24c80 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
24c90 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
24ca0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
24cb0 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
24cc0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
24cd0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
24ce0 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
24cf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24d00 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
24d10 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
24d20 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
24d30 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
24d40 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
24d50 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
24d60 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
24d70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
24d80 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
24d90 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
24da0 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
24db0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
24dc0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
24dd0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
24de0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24df0 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
24e00 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
24e10 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
24e20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
24e30 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
24e40 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
24e50 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
24e60 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
24e70 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
24e80 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
24e90 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
24ea0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
24eb0 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
24ec0 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
24ed0 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
24ee0 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
24ef0 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
24f00 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
24f10 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
24f20 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
24f30 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
24f40 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
24f50 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
24f60 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
24f70 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
24f80 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
24f90 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
24fa0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
24fb0 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
24fc0 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
24fd0 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
24fe0 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
24ff0 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
25000 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
25010 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
25020 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
25030 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
25040 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
25050 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
25060 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
25070 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
25080 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
25090 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
250a0 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
250b0 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
250c0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
250d0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
250e0 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
250f0 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
25100 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
25110 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  osed..**.** [[UR
25120 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73  I filenames in s
25130 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20  qlite3_open()]] 
25140 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65  <h3>URI Filename
25150 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66  s</h3>.**.** ^If
25160 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
25170 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
25180 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74  s enabled, and t
25190 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
251a0 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77  ment.** begins w
251b0 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65  ith "file:", the
251c0 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  n the filename i
251d0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
251e0 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20   a URI. ^URI.** 
251f0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
25200 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
25210 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ed if the [SQLIT
25220 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
25230 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68   is.** set in th
25240 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
25250 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
25260 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74  n_v2(), or if it
25270 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61   has.** been ena
25280 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73  bled globally us
25290 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
252a0 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69  CONFIG_URI] opti
252b0 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  on with the.** [
252c0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
252d0 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74  ] method or by t
252e0 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  he [SQLITE_USE_U
252f0 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  RI] compile-time
25300 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f   option..** As o
25310 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
25320 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65   3.7.7, URI file
25330 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
25340 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66  ion is turned of
25350 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c  f.** by default,
25360 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65   but future rele
25370 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ases of SQLite m
25380 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20  ight enable URI 
25390 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65  filename.** inte
253a0 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65  rpretation by de
253b0 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52  fault.  See "[UR
253c0 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f  I filenames]" fo
253d0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
253e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
253f0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
25400 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
25410 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38  rding to RFC 398
25420 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63  6. ^If the URI c
25430 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75  ontains an.** au
25440 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74  thority, then it
25450 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
25460 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
25470 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a  or the string .*
25480 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e  * "localhost". ^
25490 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  If the authority
254a0 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79   is not an empty
254b0 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61   string or "loca
254c0 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65  lhost", an .** e
254d0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
254e0 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   to the caller. 
254f0 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f  ^The fragment co
25500 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
25510 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74  , if .** present
25520 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  , is ignored..**
25530 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
25540 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e   the path compon
25550 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61  ent of the URI a
25560 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
25570 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77  e disk file.** w
25580 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68  hich contains th
25590 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20  e database. ^If 
255a0 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20  the path begins 
255b0 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61  with a '/' chara
255c0 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69  cter, .** then i
255d0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
255e0 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   as an absolute 
255f0 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61  path. ^If the pa
25600 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69  th does not begi
25610 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27  n .** with a '/'
25620 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74   (meaning that t
25630 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63  he authority sec
25640 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20  tion is omitted 
25650 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a  from the URI).**
25660 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69   then the path i
25670 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
25680 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
25690 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f  . .** ^(On windo
256a0 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f  ws, the first co
256b0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62  mponent of an ab
256c0 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20  solute path .** 
256d0 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69  is a drive speci
256e0 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22  fication (e.g. "
256f0 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  C:").)^.**.** [[
25700 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
25710 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
25720 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
25730 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
25740 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
25750 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
25760 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
25770 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
25780 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
25790 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
257a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
257b0 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73  * SQLite and its
257c0 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73   built-in [VFSes
257d0 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a  ] interpret the.
257e0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65  ** following que
257f0 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a  ry parameters:.*
25800 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
25810 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20  li> <b>vfs</b>: 
25820 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d  ^The "vfs" param
25830 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64  eter may be used
25840 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
25850 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61  name of.**     a
25860 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74   VFS object that
25870 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70   provides the op
25880 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
25890 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68  nterface that sh
258a0 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75  ould.**     be u
258b0 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68  sed to access th
258c0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
258d0 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69  on disk. ^If thi
258e0 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  s option is set 
258f0 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70  to.**     an emp
25900 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65  ty string the de
25910 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74  fault VFS object
25920 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69   is used. ^Speci
25930 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
25940 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61  .**     VFS is a
25950 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c  n error. ^If sql
25960 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
25970 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76  s used and the v
25980 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  fs option is.** 
25990 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65      present, the
259a0 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66  n the VFS specif
259b0 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f  ied by the optio
259c0 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e  n takes preceden
259d0 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74  ce over.**     t
259e0 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
259f0 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  as the fourth pa
25a00 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
25a10 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
25a20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f  .**   <li> <b>mo
25a30 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f  de</b>: ^(The mo
25a40 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  de parameter may
25a50 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
25a60 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a  r "ro", "rw",.**
25a70 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22       "rwc", or "
25a80 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74  memory". Attempt
25a90 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f  ing to set it to
25aa0 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65   any other value
25ab0 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72   is.**     an er
25ac0 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e  ror)^. .**     ^
25ad0 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69  If "ro" is speci
25ae0 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64  fied, then the d
25af0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
25b00 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  d for read-only 
25b10 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
25b20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b  just as if the [
25b30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
25b40 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62  ONLY] flag had b
25b50 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a  een set in the .
25b60 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67  **     third arg
25b70 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
25b80 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20  _open_v2(). ^If 
25b90 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
25ba0 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20  is set to .**   
25bb0 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65    "rw", then the
25bc0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
25bd0 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69  ned for read-wri
25be0 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61  te (but not crea
25bf0 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  te) .**     acce
25c00 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45  ss, as if SQLITE
25c10 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
25c20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f  (but not SQLITE_
25c30 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64  OPEN_CREATE) had
25c40 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65   .**     been se
25c50 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20  t. ^Value "rwc" 
25c60 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
25c70 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a   setting both .*
25c80 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
25c90 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20  N_READWRITE and 
25ca0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
25cb0 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64  TE.  ^If the mod
25cc0 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  e option is.**  
25cd0 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72     set to "memor
25ce0 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b  y" then a pure [
25cf0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
25d00 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72  se] that never r
25d10 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77  eads.**     or w
25d20 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20  rites from disk 
25d30 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20  is used. ^It is 
25d40 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63  an error to spec
25d50 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a  ify a value for.
25d60 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20  **     the mode 
25d70 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
25d80 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69  s less restricti
25d90 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65  ve than that spe
25da0 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
25db0 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65   the flags passe
25dc0 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  d in the third p
25dd0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
25de0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
25df0 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63  *.**   <li> <b>c
25e00 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63  ache</b>: ^The c
25e10 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d  ache parameter m
25e20 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
25e30 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a  her "shared" or.
25e40 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22  **     "private"
25e50 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f  . ^Setting it to
25e60 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75   "shared" is equ
25e70 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
25e80 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51  ng the.**     SQ
25e90 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
25ea0 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65  CACHE bit in the
25eb0 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
25ec0 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  passed to.**    
25ed0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
25ee0 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65  (). ^Setting the
25ef0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
25f00 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73   to "private" is
25f10 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c   .**     equival
25f20 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
25f30 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  he SQLITE_OPEN_P
25f40 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e  RIVATECACHE bit.
25f50 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69  .**     ^If sqli
25f60 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
25f70 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63   used and the "c
25f80 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20  ache" parameter 
25f90 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a  is present in.**
25fa0 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e       a URI filen
25fb0 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f  ame, its value o
25fc0 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68  verrides any beh
25fd0 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20  avior requested 
25fe0 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  by setting.**   
25ff0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52    SQLITE_OPEN_PR
26000 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51  IVATECACHE or SQ
26010 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
26020 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a  CACHE flag..**.*
26030 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c  *  <li> <b>psow<
26040 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70  /b>: ^The psow p
26050 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74  arameter indicat
26060 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  es whether or no
26070 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f  t the.**     [po
26080 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74  wersafe overwrit
26090 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73  e] property does
260a0 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70   or does not app
260b0 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  ly to the.**    
260c0 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f   storage media o
260d0 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61  n which the data
260e0 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65  base file reside
260f0 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  s..**.**  <li> <
26100 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54  b>nolock</b>: ^T
26110 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65  he nolock parame
26120 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
26130 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
26140 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66  .**     which if
26150 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69   set disables fi
26160 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f  le locking in ro
26170 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d  llback journal m
26180 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20  odes.  This.**  
26190 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72     is useful for
261a0 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74   accessing a dat
261b0 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73  abase on a files
261c0 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20  ystem that does 
261d0 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f  not.**     suppo
261e0 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75  rt locking.  Cau
261f0 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20  tion:  Database 
26200 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74  corruption might
26210 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a   result if two.*
26220 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72  *     or more pr
26230 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f  ocesses write to
26240 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
26250 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f  se and any one o
26260 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70  f those.**     p
26270 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f  rocesses uses no
26280 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c  lock=1..**.**  <
26290 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65  li> <b>immutable
262a0 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74  </b>: ^The immut
262b0 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69  able parameter i
262c0 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72  s a boolean quer
262d0 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74  y.**     paramet
262e0 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  er that indicate
262f0 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
26300 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72  ase file is stor
26310 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61  ed on.**     rea
26320 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e  d-only media.  ^
26330 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69  When immutable i
26340 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73  s set, SQLite as
26350 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
26360 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66  *     database f
26370 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  ile cannot be ch
26380 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61  anged, even by a
26390 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69   process with hi
263a0 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76  gher.**     priv
263b0 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68  ilege, and so th
263c0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
263d0 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61  ened read-only a
263e0 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a  nd all locking.*
263f0 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65  *     and change
26400 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69   detection is di
26410 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e  sabled.  Caution
26420 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d  : Setting the im
26430 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70  mutable.**     p
26440 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74  roperty on a dat
26450 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20  abase file that 
26460 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61  does in fact cha
26470 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a  nge can result.*
26480 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65  *     in incorre
26490 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  ct query results
264a0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
264b0 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e  CORRUPT] errors.
264c0 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f  .**     See also
264d0 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  : [SQLITE_IOCAP_
264e0 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20  IMMUTABLE]..**  
264f0 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a       .** </ul>.*
26500 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67  *.** ^Specifying
26510 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61   an unknown para
26520 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65  meter in the que
26530 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
26540 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a  a URI is not an.
26550 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72  ** error.  Futur
26560 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
26570 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72  Lite might under
26580 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c  stand additional
26590 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
265a0 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65  ters.  See "[que
265b0 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69  ry parameters wi
265c0 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69  th special meani
265d0 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66  ng to SQLite]" f
265e0 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
265f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
26600 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
26610 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68  me examples]] <h
26620 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  3>URI filename e
26630 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  xamples</h3>.**.
26640 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
26650 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65  ="1" align=cente
26660 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e  r cellpadding=5>
26670 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49  .** <tr><th> URI
26680 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20   filenames <th> 
26690 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c  Results.** <tr><
266a0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
266b0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
266c0 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65     Open the file
266d0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
266e0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
266f0 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ory..** <tr><td>
26700 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
26710 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20  /data.db<br>.** 
26720 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
26730 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
26740 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20  db <br> .**     
26750 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61       file://loca
26760 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f  lhost/home/fred/
26770 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64  data.db <br> <td
26780 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
26790 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
267a0 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
267b0 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c  d/data.db"..** <
267c0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64  tr><td> file://d
267d0 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65  arkstar/home/fre
267e0 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  d/data.db <td> .
267f0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
26800 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22  rror. "darkstar"
26810 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e   is not a recogn
26820 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a  ized authority..
26830 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65  ** <tr><td style
26840 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f  ="white-space:no
26850 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20  wrap"> .**      
26860 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44      file:///C:/D
26870 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32  ocuments%20and%2
26880 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44  0Settings/fred/D
26890 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a  esktop/data.db.*
268a0 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f  *     <td> Windo
268b0 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68  ws only: Open th
268c0 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
268d0 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74   on fred's deskt
268e0 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20  op on drive.**  
268f0 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65          C:. Note
26900 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73   that the %20 es
26910 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65  caping in this e
26920 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74  xample is not st
26930 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20  rictly .**      
26940 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20      necessary - 
26950 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73  space characters
26960 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74   can be used lit
26970 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20  erally.**       
26980 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61     in URI filena
26990 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  mes..** <tr><td>
269a0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
269b0 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76  de=ro&cache=priv
269c0 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  ate <td> .**    
269d0 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
269e0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
269f0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
26a00 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ry for read-only
26a10 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20   access..**     
26a20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20       Regardless 
26a30 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
26a40 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d  t shared-cache m
26a50 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62  ode is enabled b
26a60 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  y.**          de
26a70 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69  fault, use a pri
26a80 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c  vate cache..** <
26a90 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
26aa0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f  me/fred/data.db?
26ab0 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65  vfs=unix-dotfile
26ac0 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20   <td>.**        
26ad0 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f    Open file "/ho
26ae0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
26af0 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61  . Use the specia
26b00 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66  l VFS "unix-dotf
26b10 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20  ile".**         
26b20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66   that uses dot-f
26b30 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66  iles in place of
26b40 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20   posix advisory 
26b50 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e  locking..** <tr>
26b60 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
26b70 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20  b?mode=readonly 
26b80 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
26b90 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61    An error. "rea
26ba0 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20  donly" is not a 
26bb0 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72  valid option for
26bc0 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61   the "mode" para
26bd0 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c  meter..** </tabl
26be0 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65  e>.**.** ^URI he
26bf0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
26c00 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29   sequences (%HH)
26c10 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77   are supported w
26c20 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61  ithin the path a
26c30 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70  nd.** query comp
26c40 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e  onents of a URI.
26c50 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65   A hexadecimal e
26c60 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63  scape sequence c
26c70 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20  onsists of a.** 
26c80 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22  percent sign - "
26c90 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79  %" - followed by
26ca0 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78   exactly two hex
26cb0 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20  adecimal digits 
26cc0 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61  .** specifying a
26cd0 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e  n octet value. ^
26ce0 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20  Before the path 
26cf0 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  or query compone
26d00 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20  nts of a.** URI 
26d10 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74  filename are int
26d20 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61  erpreted, they a
26d30 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  re encoded using
26d40 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a   UTF-8 and all .
26d50 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  ** hexadecimal e
26d60 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
26d70 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69  replaced by a si
26d80 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69  ngle byte contai
26d90 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72  ning the.** corr
26da0 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e  esponding octet.
26db0 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73   If this process
26dc0 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e   generates an in
26dd0 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f  valid UTF-8 enco
26de0 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73  ding,.** the res
26df0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
26e00 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
26e10 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
26e20 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
26e30 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
26e40 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
26e50 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
26e60 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
26e70 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
26e80 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
26e90 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
26ea0 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
26eb0 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
26ec0 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
26ed0 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
26ee0 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
26ef0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
26f00 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
26f10 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
26f20 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
26f30 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
26f40 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
26f50 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
26f60 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75  indows Runtime u
26f70 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74  sers:</b>  The t
26f80 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f  emporary directo
26f90 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a  ry must be set.*
26fa0 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
26fb0 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ng sqlite3_open(
26fc0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
26fd0 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69  n_v2().  Otherwi
26fe0 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66  se, various.** f
26ff0 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71  eatures that req
27000 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20  uire the use of 
27010 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20  temporary files 
27020 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20  may fail..**.** 
27030 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
27040 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
27050 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  y].*/.SQLITE_API
27060 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65   int sqlite3_ope
27070 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
27080 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
27090 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
270a0 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
270b0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
270c0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
270d0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
270e0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
270f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65   int sqlite3_ope
27100 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
27110 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
27120 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
27130 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
27140 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
27150 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
27160 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
27170 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  le */.);.SQLITE_
27180 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
27190 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
271a0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
271b0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
271c0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
271d0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
271e0 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
271f0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
27200 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
27210 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
27220 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
27230 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
27240 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
27250 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
27260 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
27270 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
27280 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55  ain Values For U
27290 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  RI Parameters.**
272a0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74  .** These are ut
272b0 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20  ility routines, 
272c0 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d  useful to VFS im
272d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74  plementations, t
272e0 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20  hat check.** to 
272f0 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73  see if a databas
27300 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49  e file was a URI
27310 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20   that contained 
27320 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79  a specific query
27330 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20   .** parameter, 
27340 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e  and if so obtain
27350 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
27360 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65  hat query parame
27370 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20  ter..**.** If F 
27380 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  is the database 
27390 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72  filename pointer
273a0 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
273b0 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20   xOpen() method 
273c0 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70  of .** a VFS imp
273d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e  lementation when
273e0 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
273f0 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20  eter to xOpen() 
27400 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d  has one or .** m
27410 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
27420 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20  TE_OPEN_URI] or 
27430 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
27440 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61  N_DB] bits set a
27450 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e  nd.** P is the n
27460 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79  ame of the query
27470 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
27480 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
27490 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
274a0 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
274b0 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72   of the P.** par
274c0 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69  ameter if it exi
274d0 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  sts or a NULL po
274e0 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20  inter if P does 
274f0 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20  not appear as a 
27500 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
27510 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20  ter on F.  If P 
27520 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d  is a query param
27530 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73  eter of F.** has
27540 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c   no explicit val
27550 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ue, then sqlite3
27560 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
27570 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ,P) returns.** a
27580 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65   pointer to an e
27590 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
275a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
275b0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
275c0 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65  ) routine assume
275d0 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f  s that P is a bo
275e0 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74  olean.** paramet
275f0 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
27600 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65  rue (1) or false
27610 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74   (0) according t
27620 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f  o the value.** o
27630 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65  f P.  The sqlite
27640 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
27650 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74  P,B) routine ret
27660 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66  urns true (1) if
27670 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
27680 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
27690 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65   P is one of "ye
276a0 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22  s", "true", or "
276b0 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61  on" in any.** ca
276c0 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c  se or if the val
276d0 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
276e0 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72   non-zero number
276f0 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74  .  The .** sqlit
27700 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
27710 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72  ,P,B) routines r
27720 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29  eturns false (0)
27730 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
27740 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
27750 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
27760 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f  "no", "false", o
27770 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63  r "off" in any c
27780 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65  ase or.** if the
27790 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
277a0 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72  th a numeric zer
277b0 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20  o.  If P is not 
277c0 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  a query.** param
277d0 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20  eter on F or if 
277e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
277f0 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  s does not match
27800 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61   any of the.** a
27810 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  bove, then sqlit
27820 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
27830 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42  ,P,B) returns (B
27840 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  !=0)..**.** The 
27850 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
27860 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65  4(F,P,D) routine
27870 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61   converts the va
27880 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a  lue of P into a.
27890 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ** 64-bit signed
278a0 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74   integer and ret
278b0 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65  urns that intege
278c0 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65  r, or D if P doe
278d0 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20  s not.** exist. 
278e0 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   If the value of
278f0 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20   P is something 
27900 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e  other than an in
27910 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a  teger, then.** z
27920 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
27930 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20  .** .** If F is 
27940 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
27950 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
27960 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
27970 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
27980 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
27990 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
279a0 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20  eturns B.  If F 
279b0 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f  is not a NULL po
279c0 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20  inter and.** is 
279d0 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
279e0 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69  ile pathname poi
279f0 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  nter that SQLite
27a00 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
27a10 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65   xOpen.** VFS me
27a20 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62  thod, then the b
27a30 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
27a40 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66  routine is undef
27a50 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
27a60 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  y.** undesirable
27a70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
27a80 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
27a90 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
27aa0 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
27ab0 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
27ac0 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51  har *zParam);.SQ
27ad0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
27ae0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
27af0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
27b00 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  le, const char *
27b10 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66  zParam, int bDef
27b20 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ault);.SQLITE_AP
27b30 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
27b40 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
27b50 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63  4(const char*, c
27b60 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
27b70 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a  te3_int64);.../*
27b80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
27b90 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
27ba0 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  ssages.** METHOD
27bb0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
27bc0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
27bd0 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  ent sqlite3_* AP
27be0 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  I call associate
27bf0 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61  d with .** [data
27c00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
27c10 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20   D failed, then 
27c20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  the sqlite3_errc
27c30 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65  ode(D) interface
27c40 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
27c50 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
27c60 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
27c70 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
27c80 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20  for that.** API 
27c90 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20  call..** If the 
27ca0 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
27cb0 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73  call was success
27cc0 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ful,.** then the
27cd0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
27ce0 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  om sqlite3_errco
27cf0 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
27d00 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
27d10 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
27d20 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
27d30 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
27d40 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
27d50 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
27d60 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
27d70 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
27d80 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
27d90 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
27da0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
27db0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
27dc0 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
27dd0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
27de0 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
27df0 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
27e00 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
27e10 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
27e20 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
27e30 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
27e40 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
27e50 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
27e60 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
27e70 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
27e80 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ally..** The app
27e90 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  lication does no
27ea0 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20  t need to worry 
27eb0 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68  about freeing th
27ec0 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77  e result..** How
27ed0 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20  ever, the error 
27ee0 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20  string might be 
27ef0 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
27f00 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a  eallocated by.**
27f10 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
27f20 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  s to other SQLit
27f30 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  e interface func
27f40 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  tions.)^.**.** ^
27f50 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73  The sqlite3_errs
27f60 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  tr() interface r
27f70 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69  eturns the Engli
27f80 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74  sh-language text
27f90 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62  .** that describ
27fa0 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63  es the [result c
27fb0 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a  ode], as UTF-8..
27fc0 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
27fd0 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
27fe0 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
27ff0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
28000 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e  ly.** and must n
28010 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74  ot be freed by t
28020 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e  he application)^
28030 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
28040 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
28050 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
28060 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74  in use, it might
28070 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20   be the.** case 
28080 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72  that a second er
28090 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20  ror occurs on a 
280a0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
280b0 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  in between.** th
280c0 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69  e time of the fi
280d0 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68  rst error and th
280e0 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20  e call to these 
280f0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57  interfaces..** W
28100 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73  hen that happens
28110 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72  , the second err
28120 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72  or will be repor
28130 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a  ted since these.
28140 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c  ** interfaces al
28150 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20  ways report the 
28160 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75  most recent resu
28170 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a  lt.  To avoid.**
28180 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65   this, each thre
28190 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78  ad can obtain ex
281a0 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74  clusive use of t
281b0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
281c0 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79  nection] D.** by
281d0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
281e0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28  e3_mutex_enter](
281f0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
28200 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65  x](D)) before be
28210 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73  ginning.** to us
28220 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  e D and invoking
28230 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
28240 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f  leave]([sqlite3_
28250 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66  db_mutex](D)) af
28260 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73  ter.** all calls
28270 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63   to the interfac
28280 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61  es listed here a
28290 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a  re completed..**
282a0 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
282b0 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
282c0 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
282d0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
282e0 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
282f0 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
28300 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
28310 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
28320 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
28330 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
28340 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
28350 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c  t be set..*/.SQL
28360 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
28370 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
28380 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45  te3 *db);.SQLITE
28390 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
283a0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
283b0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
283c0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
283d0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
283e0 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
283f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
28400 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
28410 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
28420 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
28430 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
28440 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a  e3_errstr(int);.
28450 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28460 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
28470 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
28480 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
28490 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
284a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
284b0 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
284c0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
284d0 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
284e0 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
284f0 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61  ement that.** ha
28500 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20  s been compiled 
28510 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d  into binary form
28520 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f   and is ready to
28530 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a   be evaluated..*
28540 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61  *.** Think of ea
28550 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
28560 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20 63   as a separate c
28570 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e  omputer program.
28580 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61    The.** origina
28590 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f  l SQL text is so
285a0 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72  urce code.  A pr
285b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
285c0 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74   object .** is t
285d0 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65  he compiled obje
285e0 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51  ct code.  All SQ
285f0 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  L must be conver
28600 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72  ted into a.** pr
28610 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28620 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62   before it can b
28630 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  e run..**.** The
28640 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61   life-cycle of a
28650 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
28660 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c  ent object usual
28670 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69  ly goes like thi
28680 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
28690 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
286a0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
286b0 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  ent object using
286c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
286d0 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e  e_v2()]..** <li>
286e0 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
286f0 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69  [parameters] usi
28700 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
28710 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
28720 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
28730 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
28740 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
28750 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
28760 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
28770 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
28780 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
28790 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
287a0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
287b0 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
287c0 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
287d0 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
287e0 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
287f0 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
28800 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
28810 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
28820 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65  ** </ol>.*/.type
28830 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
28840 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
28850 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
28860 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
28870 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44  Limits.** METHOD
28880 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
28890 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
288a0 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
288b0 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
288c0 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
288d0 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
288e0 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
288f0 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
28900 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
28910 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
28920 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28930 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
28940 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
28950 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
28960 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
28970 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
28980 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
28990 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
289a0 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
289b0 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
289c0 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
289d0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
289e0 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
289f0 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
28a00 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
28a10 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
28a20 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
28a30 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
28a40 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
28a50 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
28a60 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
28a70 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
28a80 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
28a90 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
28aa0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
28ab0 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
28ac0 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
28ad0 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
28ae0 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
28af0 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
28b00 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
28b10 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
28b20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
28b30 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
28b40 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
28b50 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
28b60 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
28b70 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
28b80 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
28b90 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
28ba0 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
28bb0 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
28bc0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
28bd0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
28be0 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
28bf0 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
28c00 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
28c10 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
28c20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
28c30 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
28c40 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
28c50 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
28c60 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
28c70 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
28c80 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
28c90 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
28ca0 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
28cb0 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
28cc0 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
28cd0 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
28ce0 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
28cf0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
28d00 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
28d10 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
28d20 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
28d30 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
28d40 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
28d50 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
28d60 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
28d70 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
28d80 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
28d90 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
28da0 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
28db0 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
28dc0 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
28dd0 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
28de0 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
28df0 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
28e00 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
28e10 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
28e20 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
28e30 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
28e40 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
28e50 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
28e60 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
28e70 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
28e80 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
28e90 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
28ea0 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
28eb0 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
28ec0 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
28ed0 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
28ee0 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
28ef0 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
28f00 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
28f10 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
28f20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
28f30 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
28f40 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
28f50 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
28f60 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
28f70 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
28f80 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
28f90 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
28fa0 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
28fb0 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
28fc0 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
28fd0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
28fe0 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
28ff0 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
29000 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
29010 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
29020 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  es..*/.SQLITE_AP
29030 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  I int sqlite3_li
29040 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
29050 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
29060 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29070 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
29080 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a  it Categories.**
29090 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69   KEYWORDS: {limi
290a0 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69  t category} {*li
290b0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
290c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
290d0 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
290e0 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65  ious performance
290f0 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20   limits.** that 
29100 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61  can be lowered a
29110 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67  t run-time using
29120 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
29130 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70  )]..** The synop
29140 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69  sis of the meani
29150 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
29160 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f  us limits is sho
29170 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64  wn below..** Add
29180 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
29190 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ion is available
291a0 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69   at [limits | Li
291b0 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e  mits in SQLite].
291c0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
291d0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
291e0 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
291f0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
29200 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
29210 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
29220 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
29230 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
29240 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29  , in bytes.<dd>)
29250 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
29260 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
29270 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
29280 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
29290 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
292a0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
292b0 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
292c0 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c  ment, in bytes.<
292d0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
292e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
292f0 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  MN]] ^(<dt>SQLIT
29300 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
29310 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29320 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
29330 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
29340 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
29350 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
29360 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
29370 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
29380 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
29390 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
293a0 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
293b0 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
293c0 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
293d0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
293e0 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
293f0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
29400 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
29410 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
29420 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
29430 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
29440 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
29450 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
29460 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
29470 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
29480 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
29490 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
294a0 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
294b0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
294c0 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
294d0 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
294e0 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
294f0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
29500 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
29510 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  P]] ^(<dt>SQLITE
29520 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
29530 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29540 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
29550 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
29560 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
29570 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
29580 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
29590 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
295a0 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73  .  This limit is
295b0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a   not currently.*
295c0 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75  * enforced, thou
295d0 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  gh that might be
295e0 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66   added in some f
295f0 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
29600 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  .** SQLite.</dd>
29610 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29620 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
29630 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  _ARG]] ^(<dt>SQL
29640 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
29650 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
29660 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
29670 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
29680 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
29690 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
296a0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  [SQLITE_LIMIT_AT
296b0 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53  TACHED]] ^(<dt>S
296c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
296d0 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
296e0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
296f0 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
29700 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
29710 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
29720 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29730 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
29740 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  ENGTH]].** ^(<dt
29750 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
29760 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
29770 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
29780 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
29790 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
297a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
297b0 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
297c0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
297d0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
297e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
297f0 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20  BLE_NUMBER]].** 
29800 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29810 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
29820 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
29830 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78  he maximum index
29840 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b   number of any [
29850 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e  parameter] in an
29860 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29   SQL statement.)
29870 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
29880 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
29890 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
298a0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
298b0 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
298c0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
298d0 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
298e0 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
298f0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
29900 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52  SQLITE_LIMIT_WOR
29910 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28  KER_THREADS]] ^(
29920 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29930 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c  _WORKER_THREADS<
29940 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29950 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
29960 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b  f auxiliary work
29970 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74 20  er threads that 
29980 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65  a single.** [pre
29990 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
299a0 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e   may start.</dd>
299b0 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  )^.** </dl>.*/.#
299c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
299d0 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  MIT_LENGTH      
299e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a                0.
299f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29a00 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20  IMIT_SQL_LENGTH 
29a10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
29a20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29a30 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20  LIMIT_COLUMN    
29a40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29a50 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
29a60 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
29a70 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
29a80 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
29a90 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
29aa0 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
29ab0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
29ac0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
29ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29ae0 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
29af0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
29b00 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20  ON_ARG          
29b10 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
29b20 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
29b30 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  HED             
29b40 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
29b50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
29b60 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20  _PATTERN_LENGTH 
29b70 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
29b80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
29b90 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20  IABLE_NUMBER    
29ba0 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
29bb0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52   SQLITE_LIMIT_TR
29bc0 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20  IGGER_DEPTH     
29bd0 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
29be0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  e SQLITE_LIMIT_W
29bf0 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20  ORKER_THREADS   
29c00 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a          11../*.*
29c10 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
29c20 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
29c30 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52  tement.** KEYWOR
29c40 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
29c50 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20  nt compiler}.** 
29c60 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
29c70 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
29c80 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
29c90 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
29ca0 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
29cb0 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
29cc0 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
29cd0 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
29ce0 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
29cf0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
29d00 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
29d10 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69  rgument, "db", i
29d20 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
29d30 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e  nnection] obtain
29d40 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69  ed from a.** pri
29d50 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
29d60 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
29d70 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
29d80 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a  _open_v2()] or.*
29d90 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
29da0 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62  6()].  The datab
29db0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
29dc0 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65  ust not have bee
29dd0 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  n closed..**.** 
29de0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
29df0 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20  ent, "zSql", is 
29e00 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  the statement to
29e10 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e   be compiled, en
29e20 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68  coded.** as eith
29e30 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
29e40 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  16.  The sqlite3
29e50 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73  _prepare() and s
29e60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
29e70 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  2().** interface
29e80 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64  s use UTF-8, and
29e90 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
29ea0 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  16() and sqlite3
29eb0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a  _prepare16_v2().
29ec0 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a  ** use UTF-16..*
29ed0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79  *.** ^If the nBy
29ee0 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e  te argument is n
29ef0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53  egative, then zS
29f00 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
29f10 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
29f20 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e  ro terminator. ^
29f30 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69  If nByte is posi
29f40 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
29f50 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
29f60 66 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f  f bytes read fro
29f70 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79  m zSql.  ^If nBy
29f80 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e  te is zero, then
29f90 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20   no prepared.** 
29fa0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e  statement is gen
29fb0 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68  erated..** If th
29fc0 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74  e caller knows t
29fd0 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
29fe0 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
29ff0 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a  erminated, then.
2a000 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  ** there is a sm
2a010 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  all performance 
2a020 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73  advantage to pas
2a030 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
2a040 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
2a050 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
2a060 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e   bytes in the in
2a070 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e  put string <i>in
2a080 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74  cluding</i>.** t
2a090 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
2a0a0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54  r..**.** ^If pzT
2a0b0 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ail is not NULL 
2a0c0 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
2a0d0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
2a0e0 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a   the first byte.
2a0f0 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  ** past the end 
2a100 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
2a110 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
2a120 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
2a130 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70  nes only.** comp
2a140 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74  ile the first st
2a150 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
2a160 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
2a170 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a  eft pointing to.
2a180 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  ** what remains 
2a190 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
2a1a0 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  * ^*ppStmt is le
2a1b0 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
2a1c0 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
2a1d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2a1e0 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
2a1f0 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
2a200 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
2a210 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20  ^If there is an 
2a220 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
2a230 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
2a240 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74  .  ^If the input
2a250 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
2a260 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
2a270 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
2a280 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
2a290 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
2a2a0 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
2a2b0 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ULL..** The call
2a2c0 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
2a2d0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
2a2e0 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
2a2f0 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
2a300 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
2a310 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2a320 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
2a330 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
2a340 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20  ..** ppStmt may 
2a350 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  not be NULL..**.
2a360 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20  ** ^On success, 
2a370 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  the sqlite3_prep
2a380 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20  are() family of 
2a390 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2a3a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20  [SQLITE_OK];.** 
2a3b0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
2a3c0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
2a3d0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
2a3e0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2a3f0 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
2a400 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2a410 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
2a420 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
2a430 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
2a440 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
2a450 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
2a460 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
2a470 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
2a480 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
2a490 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
2a4a0 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
2a4b0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2a4c0 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
2a4d0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
2a4e0 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
2a4f0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
2a500 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
2a510 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
2a520 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
2a530 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
2a540 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
2a550 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
2a560 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
2a570 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
2a580 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
2a590 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
2a5a0 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2a5b0 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
2a5c0 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
2a5d0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
2a5e0 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
2a5f0 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
2a600 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
2a610 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
2a620 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
2a630 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
2a640 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
2a650 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20  o run it again. 
2a660 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49  As many as [SQLI
2a670 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45  TE_MAX_SCHEMA_RE
2a680 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20  TRY].** retries 
2a690 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72  will occur befor
2a6a0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2a6b0 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65   gives up and re
2a6c0 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a  turns an error..
2a6d0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2a6e0 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
2a6f0 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
2a700 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
2a710 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
2a720 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
2a730 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
2a740 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
2a750 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
2a760 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
2a770 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
2a780 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
2a790 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
2a7a0 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
2a7b0 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
2a7c0 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
2a7d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
2a7e0 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
2a7f0 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
2a800 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2a810 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
2a820 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
2a830 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
2a840 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
2a850 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
2a860 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
2a870 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
2a880 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
2a890 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
2a8a0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
2a8b0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
2a8c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
2a8d0 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64  ific value bound
2a8e0 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c   to [parameter |
2a8f0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
2a900 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52   in the .** WHER
2a910 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69  E clause might i
2a920 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f  nfluence the cho
2a930 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
2a940 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e  n for a statemen
2a950 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73  t,.** then the s
2a960 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
2a970 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2a980 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66  ecompiled, as if
2a990 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
2a9a0 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61  .** a schema cha
2a9b0 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73  nge, on the firs
2a9c0 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  t  [sqlite3_step
2a9d0 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
2a9e0 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a  ng any change.**
2a9f0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2aa00 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
2aa10 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b  dings] of that [
2aa20 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
2aa30 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61  ^The specific va
2aa40 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61  lue of WHERE-cla
2aa50 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  use [parameter] 
2aa60 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
2aa70 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f  the .** choice o
2aa80 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20  f query plan if 
2aa90 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
2aaa0 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73   the left-hand s
2aab0 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a  ide of a [LIKE].
2aac0 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65  ** or [GLOB] ope
2aad0 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20  rator or if the 
2aae0 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d  parameter is com
2aaf0 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65  pared to an inde
2ab00 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e  xed column.** an
2ab10 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  d the [SQLITE_EN
2ab20 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70  ABLE_STAT3] comp
2ab30 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
2ab40 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c  is enabled..** <
2ab50 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f  /li>.** </ol>.*/
2ab60 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ab70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2ab80 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2ab90 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2aba0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2abb0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2abc0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2abd0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2abe0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2abf0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2ac00 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2ac10 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2ac20 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2ac30 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2ac40 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2ac50 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2ac60 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2ac70 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2ac80 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2ac90 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2aca0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53   of zSql */.);.S
2acb0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2acc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2acd0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2ace0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2acf0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2ad00 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2ad10 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2ad20 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2ad30 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
2ad40 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2ad50 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2ad60 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2ad70 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2ad80 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2ad90 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2ada0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2adb0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2adc0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
2add0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2ade0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2adf0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2ae00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2ae10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2ae20 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2ae30 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2ae40 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2ae50 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2ae60 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2ae70 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2ae80 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
2ae90 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2aea0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2aeb0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2aec0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2aed0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2aee0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2aef0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2af00 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2af10 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2af20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2af30 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2af40 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2af50 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2af60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2af70 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
2af80 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2af90 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2afa0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2afb0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2afc0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2afd0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2afe0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2aff0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2b000 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2b010 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2b020 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2b030 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2b040 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2b050 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2b060 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2b070 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2b080 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2b090 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2b0a0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
2b0b0 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
2b0c0 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
2b0d0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2b0e0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2b0f0 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29  e sqlite3_sql(P)
2b100 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2b110 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2b120 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 55 54  a copy of the UT
2b130 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  F-8.** SQL text 
2b140 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 5b  used to create [
2b150 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b160 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73 0a 2a  nt] P if P was.*
2b170 2a 20 63 72 65 61 74 65 64 20 62 79 20 65 69 74  * created by eit
2b180 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
2b190 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2b1a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b1b0 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  _v2()]..** ^The 
2b1c0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2b1d0 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63  _sql(P) interfac
2b1e0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2b1f0 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a  ter to a UTF-8.*
2b200 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
2b210 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78 74  ing the SQL text
2b220 20 6f 66 20 70 72 65 70 61 72 65 64 20 73 74 61   of prepared sta
2b230 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a 2a  tement P with.**
2b240 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65   [bound paramete
2b250 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a 2a  rs] expanded..**
2b260 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
2b270 65 2c 20 69 66 20 61 20 70 72 65 70 61 72 65 64  e, if a prepared
2b280 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72   statement is cr
2b290 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 20  eated using the 
2b2a0 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c  SQL.** text "SEL
2b2b0 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61  ECT $abc,:xyz" a
2b2c0 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65 72 20  nd if parameter 
2b2d0 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f  $abc is bound to
2b2e0 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a   integer 2345.**
2b2f0 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a   and parameter :
2b300 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20  xyz is unbound, 
2b310 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c  then sqlite3_sql
2b320 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  () will return.*
2b330 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
2b340 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24  tring, "SELECT $
2b350 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71  abc,:xyz" but sq
2b360 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2b370 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74  ql().** will ret
2b380 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35  urn "SELECT 2345
2b390 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ,NULL".)^.**.** 
2b3a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70  ^The sqlite3_exp
2b3b0 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65  anded_sql() inte
2b3c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55  rface returns NU
2b3d0 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
2b3e0 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20  nt memory.** is 
2b3f0 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c  available to hol
2b400 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72  d the result, or
2b410 20 69 66 20 74 68 65 20 72 65 73 75 6c 74 20 77   if the result w
2b420 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a  ould exceed the.
2b430 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73  ** the maximum s
2b440 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74  tring length det
2b450 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b  ermined by the [
2b460 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2b470 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  GTH]..**.** ^The
2b480 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53   [SQLITE_TRACE_S
2b490 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69  IZE_LIMIT] compi
2b4a0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c  le-time option l
2b4b0 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f  imits the size o
2b4c0 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d  f.** bound param
2b4d0 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e  eter expansions.
2b4e0 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f    ^The [SQLITE_O
2b4f0 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69  MIT_TRACE] compi
2b500 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
2b510 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74 65 33  n causes sqlite3
2b520 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20  _expanded_sql() 
2b530 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  to always return
2b540 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
2b550 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65  e string returne
2b560 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c  d by sqlite3_sql
2b570 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20 62  (P) is managed b
2b580 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73 0a  y SQLite and is.
2b590 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
2b5a0 20 66 72 65 65 64 20 77 68 65 6e 20 74 68 65 20   freed when the 
2b5b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b5c0 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 2e  nt is finalized.
2b5d0 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20  .** ^The string 
2b5e0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2b5f0 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2b600 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65  (P), on the othe
2b610 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62  r hand,.** is ob
2b620 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
2b630 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
2b640 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65 65 20  nd must be free 
2b650 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
2b660 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e 67  on.** by passing
2b670 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
2b680 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  free()]..*/.SQLI
2b690 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2b6a0 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
2b6b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2b6c0 6d 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  mt);.SQLITE_API 
2b6d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 78  char *sqlite3_ex
2b6e0 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69 74  panded_sql(sqlit
2b6f0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2b700 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b710 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2b720 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
2b730 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
2b740 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ase.** METHOD: s
2b750 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2b760 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2b770 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
2b780 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2b790 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
2b7a0 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
2b7b0 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
2b7c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
2b7d0 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
2b7e0 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
2b7f0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2b800 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
2b810 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
2b820 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2b830 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2b840 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
2b850 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
2b860 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2b870 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
2b880 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
2b890 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
2b8a0 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
2b8b0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
2b8c0 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
2b8d0 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
2b8e0 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
2b8f0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
2b900 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
2b910 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
2b920 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2b930 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
2b940 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
2b950 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
2b960 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
2b970 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
2b980 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
2b990 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
2b9a0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
2b9b0 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
2b9c0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2b9d0 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
2b9e0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
2b9f0 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
2ba00 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2ba10 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
2ba20 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
2ba30 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
2ba40 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
2ba50 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
2ba60 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
2ba70 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
2ba80 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
2ba90 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
2baa0 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
2bab0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
2bac0 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
2bad0 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
2bae0 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
2baf0 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
2bb00 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2bb10 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
2bb20 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
2bb30 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
2bb40 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
2bb50 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
2bb60 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
2bb70 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
2bb80 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
2bb90 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
2bba0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2bbb0 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
2bbc0 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
2bbd0 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
2bbe0 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
2bbf0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
2bc00 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
2bc10 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
2bc20 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
2bc30 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
2bc40 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
2bc50 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
2bc60 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73   disk..** ^The s
2bc70 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2bc80 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63 65  only() interface
2bc90 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 66 6f   returns true fo
2bca0 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65 0a  r [BEGIN] since.
2bcb0 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65 6c  ** [BEGIN] merel
2bcc0 79 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c 20  y sets internal 
2bcd0 66 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20 5b  flags, but the [
2bce0 42 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d 45  BEGIN|BEGIN IMME
2bcf0 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42  DIATE] and.** [B
2bd00 45 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c 55  EGIN|BEGIN EXCLU
2bd10 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20 64  SIVE] commands d
2bd20 6f 20 74 6f 75 63 68 20 74 68 65 20 64 61 74 61  o touch the data
2bd30 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20 73  base and so.** s
2bd40 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2bd50 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20 66  only() returns f
2bd60 61 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20 63  alse for those c
2bd70 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 53 51 4c 49  ommands..*/.SQLI
2bd80 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2bd90 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2bda0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2bdb0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2bdc0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
2bdd0 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20  e If A Prepared 
2bde0 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65  Statement Has Be
2bdf0 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48  en Reset.** METH
2be00 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2be10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2be20 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
2be30 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2be40 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
2be50 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
2be60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2be70 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
2be80 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
2be90 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
2bea0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
2beb0 75 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 72  ut has neither r
2bec0 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  un to completion
2bed0 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53   (returned.** [S
2bee0 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d  QLITE_DONE] from
2bef0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2bf00 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20  )]) nor.** been 
2bf10 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c  reset using [sql
2bf20 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20  ite3_reset(S)]. 
2bf30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2bf40 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e  mt_busy(S).** in
2bf50 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2bf60 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20  false if S is a 
2bf70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49  NULL pointer.  I
2bf80 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a  f S is not a .**
2bf90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
2bfa0 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74  d is not a point
2bfb0 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70  er to a valid [p
2bfc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2bfd0 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68  t].** object, th
2bfe0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2bff0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
2c000 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
2c010 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rable..**.** Thi
2c020 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
2c030 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69  be used in combi
2c040 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  nation [sqlite3_
2c050 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20  next_stmt()].** 
2c060 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72  to locate all pr
2c070 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c080 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
2c090 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a  h a database .**
2c0a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
2c0b0 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20   are in need of 
2c0c0 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68  being reset.  Th
2c0d0 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a  is can be used,.
2c0e0 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** for example, 
2c0f0 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f  in diagnostic ro
2c100 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68  utines to search
2c110 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a   for prepared .*
2c120 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  * statements tha
2c130 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20  t are holding a 
2c140 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e  transaction open
2c150 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2c160 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
2c170 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74  _busy(sqlite3_st
2c180 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2c190 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c  I3REF: Dynamical
2c1a0 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
2c1b0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
2c1c0 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
2c1d0 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
2c1e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c1f0 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
2c200 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
2c210 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2c220 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
2c230 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
2c240 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
2c250 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
2c260 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
2c270 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
2c280 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
2c290 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20  ues it stores.  
2c2a0 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69  ^Values stored i
2c2b0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
2c2c0 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62  objects.** can b
2c2d0 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61  e integers, floa
2c2e0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2c2f0 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42  s, strings, BLOB
2c300 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  s, or NULL..**.*
2c310 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  * An sqlite3_val
2c320 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65  ue object may be
2c330 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74   either "protect
2c340 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63  ed" or "unprotec
2c350 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e  ted"..** Some in
2c360 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
2c370 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
2c380 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68  ite3_value.  Oth
2c390 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
2c3a0 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74   will accept eit
2c3b0 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20  her a protected 
2c3c0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
2c3d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2c3e0 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66  .** Every interf
2c3f0 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73  ace that accepts
2c400 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61   sqlite3_value a
2c410 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69  rguments specifi
2c420 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72  es.** whether or
2c430 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73   not it requires
2c440 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
2c450 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65  ite3_value.  The
2c460 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2c470 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66  ue_dup()] interf
2c480 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2c490 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e  to construct a n
2c4a0 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64  ew .** protected
2c4b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66   sqlite3_value f
2c4c0 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  rom an unprotect
2c4d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c4e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
2c4f0 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
2c500 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
2c510 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
2c520 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
2c530 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
2c540 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
2c550 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
2c560 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2c570 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
2c580 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
2c590 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
2c5a0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2c5b0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
2c5c0 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
2c5d0 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
2c5e0 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
2c5f0 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
2c600 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
2c610 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
2c620 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
2c630 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
2c640 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
2c650 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
2c660 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
2c670 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
2c680 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
2c690 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2c6a0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
2c6b0 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
2c6c0 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
2c6d0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
2c6e0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
2c6f0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2c700 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
2c710 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
2c720 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
2c730 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
2c740 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
2c750 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
2c760 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
2c770 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
2c780 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
2c790 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
2c7a0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
2c7b0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2c7c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2c7d0 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
2c7e0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
2c7f0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
2c800 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2c810 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
2c820 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
2c830 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
2c840 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
2c850 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
2c860 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2c870 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
2c880 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
2c890 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2c8a0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
2c8b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2c8c0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
2c8d0 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
2c8e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2c8f0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2c900 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
2c910 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
2c920 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2c930 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2c940 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
2c950 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
2c960 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
2c970 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
2c980 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
2c990 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
2c9a0 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
2c9b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2c9c0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
2c9d0 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
2c9e0 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
2c9f0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
2ca00 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
2ca10 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
2ca20 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
2ca30 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
2ca40 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
2ca50 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
2ca60 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
2ca70 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
2ca80 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
2ca90 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
2caa0 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
2cab0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
2cac0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2cad0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2cae0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
2caf0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2cb00 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2cb10 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
2cb20 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
2cb30 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
2cb40 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2cb50 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
2cb60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
2cb70 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
2cb80 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2cb90 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
2cba0 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
2cbb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
2cbc0 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
2cbd0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2cbe0 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
2cbf0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
2cc00 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
2cc10 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2cc20 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
2cc30 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
2cc40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
2cc50 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
2cc60 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2cc70 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
2cc80 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
2cc90 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2cca0 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
2ccb0 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
2ccc0 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
2ccd0 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
2cce0 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
2ccf0 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45  r binding}.** ME
2cd00 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2cd10 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  mt.**.** ^(In th
2cd20 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2cd30 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73  text input to [s
2cd40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2cd50 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
2cd60 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
2cd70 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
2cd80 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74  ed by a [paramet
2cd90 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73  er] that matches
2cda0 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e   one of followin
2cdb0 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a  g.** templates:.
2cdc0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2cdd0 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
2cde0 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
2cdf0 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
2ce00 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
2ce10 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
2ce20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62  the templates ab
2ce30 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65  ove, NNN represe
2ce40 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c  nts an integer l
2ce50 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
2ce60 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  VV represents an
2ce70 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
2ce80 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68  entifier.)^  ^Th
2ce90 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
2cea0 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
2ceb0 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
2cec0 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
2ced0 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
2cee0 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
2cef0 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
2cf00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2cf10 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
2cf20 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed here..**.** ^
2cf30 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2cf40 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
2cf50 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2cf60 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
2cf70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2cf80 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
2cf90 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2cfa0 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
2cfb0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2cfc0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
2cfd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
2cfe0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2cff0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2d000 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
2d010 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65   be set..** ^The
2d020 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
2d030 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
2d040 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65  ndex of 1.  ^Whe
2d050 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
2d060 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
2d070 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
2d080 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
2d090 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
2d0a0 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
2d0b0 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
2d0c0 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
2d0d0 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e  occurrence..** ^
2d0e0 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
2d0f0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
2d100 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
2d110 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
2d120 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2d130 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
2d140 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e  I if desired.  ^
2d150 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
2d160 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
2d170 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
2d180 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20  of NNN..** ^The 
2d190 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
2d1a0 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
2d1b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
2d1c0 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
2d1d0 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
2d1e0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
2d1f0 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
2d200 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  : 999)..**.** ^T
2d210 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2d220 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
2d230 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
2d240 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
2d250 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2d260 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2d270 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
2d280 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2d290 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  6().** or sqlite
2d2a0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
2d2b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2d2c0 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2d2d0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20  parameter.** is 
2d2e0 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20  ignored and the 
2d2f0 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68  end result is th
2d300 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65  e same as sqlite
2d310 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a  3_bind_null()..*
2d320 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
2d330 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
2d340 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
2d350 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
2d360 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2d370 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2d380 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
2d390 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
2d3a0 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2d3b0 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
2d3c0 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
2d3d0 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
2d3e0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2d3f0 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
2d400 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2d410 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2d420 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2d430 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
2d440 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
2d450 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  hen the length o
2d460 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
2d470 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2d480 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
2d490 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
2d4a0 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68  inator..** If th
2d4b0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2d4c0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2d4d0 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67  nd_blob() is neg
2d4e0 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74  ative, then.** t
2d4f0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2d500 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
2d510 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66  a non-negative f
2d520 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2d530 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  is provided to s
2d540 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2d550 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2d560 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f  _bind_text16() o
2d570 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2d580 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20  ext64() then.** 
2d590 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d  that parameter m
2d5a0 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
2d5b0 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20  offset.** where 
2d5c0 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
2d5d0 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61  or would occur a
2d5e0 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69  ssuming the stri
2d5f0 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74  ng were NUL.** t
2d600 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
2d610 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
2d620 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20  s occur at byte 
2d630 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61  offsets less tha
2d640 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n .** the value 
2d650 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
2d660 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65  rameter then the
2d670 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
2d680 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20  g value will.** 
2d690 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
2d6a0 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75   NULs.  The resu
2d6b0 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
2d6c0 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69  s involving stri
2d6d0 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65  ngs.** with embe
2d6e0 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
2d6f0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2d700 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2d710 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e  t to the BLOB an
2d720 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67  d string binding
2d730 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2d740 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
2d750 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
2d760 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
2d770 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
2d780 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
2d790 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
2d7a0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
2d7b0 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
2d7c0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2d7d0 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
2d7e0 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69  f the call to bi
2d7f0 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a  nd API fails..**
2d800 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2d810 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
2d820 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
2d830 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
2d840 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
2d850 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
2d860 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2d870 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
2d880 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
2d890 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
2d8a0 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
2d8b0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2d8c0 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
2d8d0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
2d8e0 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
2d8f0 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
2d900 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
2d910 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
2d920 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
2d930 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
2d940 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
2d950 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
2d960 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  The sixth argume
2d970 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
2d980 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74  nd_text64() must
2d990 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53   be one of.** [S
2d9a0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
2d9b0 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51  LITE_UTF16], [SQ
2d9c0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f  LITE_UTF16BE], o
2d9d0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
2d9e0 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79  E].** to specify
2d9f0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
2da00 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65   the text in the
2da10 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2da20 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78  .  If.** the six
2da30 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2da40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2da50 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  64() is not one 
2da60 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65  of the.** allowe
2da70 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61  d values shown a
2da80 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20  bove, or if the 
2da90 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73  text encoding is
2daa0 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72   different.** fr
2dab0 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  om the encoding 
2dac0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2dad0 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
2dae0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2daf0 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ior.** is undefi
2db00 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2db10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2db20 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
2db30 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
2db40 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
2db50 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
2db60 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
2db70 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
2db80 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
2db90 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
2dba0 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
2dbb0 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
2dbc0 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
2dbd0 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
2dbe0 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
2dbf0 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
2dc00 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
2dc10 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
2dc20 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
2dc30 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
2dc40 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
2dc50 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
2dc60 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
2dc70 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
2dc80 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
2dc90 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
2dca0 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
2dcb0 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49  h BLOB..**.** ^I
2dcc0 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c  f any of the sql
2dcd0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2dce0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2dcf0 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
2dd00 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65  inter.** for the
2dd10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2dd20 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20  ment] or with a 
2dd30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2dd40 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20  nt for which.** 
2dd50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2dd60 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
2dd70 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74   more recently t
2dd80 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  han [sqlite3_res
2dd90 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  et()],.** then t
2dda0 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74  he call will ret
2ddb0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
2ddc0 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c  SE].  If any sql
2ddd0 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20  ite3_bind_().** 
2dde0 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65  routine is passe
2ddf0 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  d a [prepared st
2de00 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2de10 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2de20 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  , the.** result 
2de30 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
2de40 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75   probably harmfu
2de50 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e  l..**.** ^Bindin
2de60 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
2de70 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
2de80 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
2de90 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64  ine..** ^Unbound
2dea0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2deb0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
2dec0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
2ded0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72  sqlite3_bind_* r
2dee0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
2def0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
2df00 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b  ccess or an.** [
2df10 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
2df20 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
2df30 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  ng..** ^[SQLITE_
2df40 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65  TOOBIG] might be
2df50 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
2df60 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e   size of a strin
2df70 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63  g or BLOB.** exc
2df80 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f  eeds limits impo
2df90 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
2dfa0 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
2dfb0 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72  IMIT_LENGTH]) or
2dfc0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f  .** [SQLITE_MAX_
2dfd0 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51  LENGTH]..** ^[SQ
2dfe0 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
2dff0 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
2e000 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
2e010 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
2e020 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d  e.  ^[SQLITE_NOM
2e030 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
2e040 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
2e050 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
2e060 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2e070 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2e080 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2e090 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e0a0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
2e0b0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2e0c0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2e0d0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2e0e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2e0f0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2e100 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2e110 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
2e120 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
2e130 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2e140 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73  e3_bind_blob64(s
2e150 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e160 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2e170 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a  sqlite3_uint64,.
2e180 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e190 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
2e1a0 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
2e1b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2e1c0 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
2e1d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2e1e0 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f  double);.SQLITE_
2e1f0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2e200 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
2e210 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
2e220 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2e230 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
2e240 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
2e250 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
2e260 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f  _int64);.SQLITE_
2e270 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2e280 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
2e290 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53  3_stmt*, int);.S
2e2a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2e2b0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2e2c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2e2d0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e  t,const char*,in
2e2e0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
2e2f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2e300 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2e310 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2e320 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2e330 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
2e340 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
2e350 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2e360 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2e370 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e380 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
2e390 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
2e3a0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2e3b0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
2e3c0 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e  )(void*), unsign
2e3d0 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67  ed char encoding
2e3e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2e3f0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  t sqlite3_bind_v
2e400 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
2e410 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
2e420 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2e430 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2e440 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2e450 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2e460 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
2e470 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2e480 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2e490 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  oblob64(sqlite3_
2e4a0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
2e4b0 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a  te3_uint64);../*
2e4c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2e4d0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
2e4e0 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44  meters.** METHOD
2e4f0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2e500 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
2e510 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
2e520 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
2e530 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
2e540 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
2e550 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e560 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
2e570 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
2e580 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
2e590 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
2e5a0 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
2e5b0 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
2e5c0 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
2e5d0 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
2e5e0 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
2e5f0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
2e600 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
2e610 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
2e620 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
2e630 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
2e640 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
2e650 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2e660 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
2e670 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
2e680 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
2e690 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
2e6a0 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
2e6b0 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
2e6c0 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
2e6d0 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
2e6e0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
2e6f0 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
2e700 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
2e710 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
2e720 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
2e730 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2e740 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2e750 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2e760 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2e770 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
2e780 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2e790 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2e7a0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
2e7b0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2e7c0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2e7d0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2e7e0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2e7f0 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
2e800 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
2e810 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2e820 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2e830 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2e840 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2e850 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  P,N) interface r
2e860 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61  eturns.** the na
2e870 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b  me of the N-th [
2e880 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
2e890 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
2e8a0 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
2e8b0 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72   ^(SQL parameter
2e8c0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
2e8d0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
2e8e0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
2e8f0 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
2e900 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
2e910 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
2e920 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
2e930 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
2e940 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
2e950 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
2e960 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
2e970 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
2e980 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
2e990 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
2e9a0 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61  e name.)^.** ^Pa
2e9b0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
2e9c0 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
2e9d0 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
2e9e0 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
2e9f0 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66  e.** and are ref
2ea00 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d  erred to as "nam
2ea10 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79  eless" or "anony
2ea20 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
2ea30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2ea40 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
2ea50 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
2ea60 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
2ea70 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
2ea80 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
2ea90 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68  e or if the N-th
2eaa0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
2eab0 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
2eac0 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
2ead0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
2eae0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
2eaf0 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
2eb00 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
2eb10 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
2eb20 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
2eb30 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
2eb40 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
2eb50 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2eb60 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2eb70 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2eb80 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2eb90 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2eba0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2ebb0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2ebc0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2ebd0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
2ebe0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2ebf0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2ec00 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2ec10 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2ec20 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2ec30 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
2ec40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
2ec50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ec60 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
2ec70 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
2ec80 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44  n Name.** METHOD
2ec90 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2eca0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
2ecb0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
2ecc0 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
2ecd0 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
2ece0 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
2ecf0 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
2ed00 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
2ed10 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
2ed20 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2ed30 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2ed40 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
2ed50 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
2ed60 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
2ed70 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
2ed80 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
2ed90 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
2eda0 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
2edb0 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
2edc0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
2edd0 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
2ede0 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
2edf0 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
2ee00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2ee10 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
2ee20 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2ee30 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2ee40 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2ee50 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2ee60 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2ee70 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2ee80 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2ee90 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  _name()]..*/.SQL
2eea0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2eeb0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2eec0 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
2eed0 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
2eee0 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
2eef0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2ef00 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
2ef10 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
2ef20 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f  atement.** METHO
2ef30 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2ef40 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
2ef50 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
2ef60 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
2ef70 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
2ef80 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
2ef90 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2efa0 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
2efb0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
2efc0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2efd0 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
2efe0 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
2eff0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
2f000 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45   NULL..*/.SQLITE
2f010 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2f020 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
2f030 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2f040 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f050 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
2f060 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
2f070 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
2f080 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2f090 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
2f0a0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2f0b0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
2f0c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2f0d0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2f0e0 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66 20 74 68  atement]. ^If th
2f0f0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
2f100 6e 73 20 30 2c 20 74 68 61 74 20 6d 65 61 6e 73  ns 0, that means
2f110 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72   the .** [prepar
2f120 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 72 65  ed statement] re
2f130 74 75 72 6e 73 20 6e 6f 20 64 61 74 61 20 28 66  turns no data (f
2f140 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55  or example an [U
2f150 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77  PDATE])..** ^How
2f160 65 76 65 72 2c 20 6a 75 73 74 20 62 65 63 61 75  ever, just becau
2f170 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
2f180 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69  returns a positi
2f190 76 65 20 6e 75 6d 62 65 72 20 64 6f 65 73 20 6e  ve number does n
2f1a0 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  ot.** mean that 
2f1b0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73  one or more rows
2f1c0 20 6f 66 20 64 61 74 61 20 77 69 6c 6c 20 62 65   of data will be
2f1d0 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 41 20 53   returned.  ^A S
2f1e0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 0a  ELECT statement.
2f1f0 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 68  ** will always h
2f200 61 76 65 20 61 20 70 6f 73 69 74 69 76 65 20 73  ave a positive s
2f210 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2f220 75 6e 74 28 29 20 62 75 74 20 64 65 70 65 6e 64  unt() but depend
2f230 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a 20 57 48  ing on the.** WH
2f240 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74  ERE clause const
2f250 72 61 69 6e 74 73 20 61 6e 64 20 74 68 65 20 74  raints and the t
2f260 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c 20 69 74  able content, it
2f270 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 6e 6f   might return no
2f280 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   rows..**.** See
2f290 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2f2a0 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  data_count()].*/
2f2b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2f2c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2f2d0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2f2e0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2f2f0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
2f300 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
2f310 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
2f320 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2f330 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2f340 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2f350 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
2f360 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
2f370 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
2f380 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
2f390 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2f3a0 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
2f3b0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2f3c0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2f3d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2f3e0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2f3f0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
2f400 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
2f410 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
2f420 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2f430 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2f440 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
2f450 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2f460 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2f470 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
2f480 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
2f490 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
2f4a0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2f4b0 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
2f4c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2f4d0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
2f4e0 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
2f4f0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
2f500 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
2f510 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2f520 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
2f530 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
2f540 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2f550 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
2f560 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
2f570 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2f580 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
2f590 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
2f5a0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
2f5b0 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
2f5c0 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
2f5d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
2f5e0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2f5f0 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
2f600 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
2f610 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2f620 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
2f630 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2f640 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
2f650 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2f660 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
2f670 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
2f680 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
2f690 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
2f6a0 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
2f6b0 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
2f6c0 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
2f6d0 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
2f6e0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
2f6f0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2f700 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
2f710 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
2f720 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
2f730 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
2f740 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
2f750 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
2f760 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
2f770 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
2f780 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
2f790 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
2f7a0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
2f7b0 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
2f7c0 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
2f7d0 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
2f7e0 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
2f7f0 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
2f800 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2f810 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2f820 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f830 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41  int N);.SQLITE_A
2f840 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2f850 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2f860 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2f870 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
2f880 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
2f890 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
2f8a0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2f8b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2f8c0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2f8d0 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
2f8e0 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
2f8f0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
2f900 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2f910 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
2f920 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
2f930 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
2f940 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
2f950 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
2f960 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
2f970 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
2f980 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
2f990 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
2f9a0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
2f9b0 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
2f9c0 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
2f9d0 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
2f9e0 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
2f9f0 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
2fa00 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
2fa10 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
2fa20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
2fa30 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
2fa40 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
2fa50 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
2fa60 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
2fa70 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2fa80 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
2fa90 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
2faa0 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
2fab0 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
2fac0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2fad0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2fae0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2faf0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2fb00 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2fb10 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2fb20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2fb30 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2fb40 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2fb50 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
2fb60 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
2fb70 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
2fb80 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
2fb90 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
2fba0 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
2fbb0 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
2fbc0 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
2fbd0 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
2fbe0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2fbf0 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
2fc00 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
2fc10 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
2fc20 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
2fc30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2fc40 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
2fc50 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
2fc60 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2fc70 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
2fc80 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2fc90 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
2fca0 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
2fcb0 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
2fcc0 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
2fcd0 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
2fce0 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
2fcf0 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
2fd00 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
2fd10 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
2fd20 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
2fd30 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
2fd40 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
2fd50 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
2fd60 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
2fd70 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
2fd80 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
2fd90 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
2fda0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
2fdb0 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
2fdc0 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
2fdd0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
2fde0 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
2fdf0 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
2fe00 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2fe10 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
2fe20 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2fe30 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
2fe40 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
2fe50 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
2fe60 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
2fe70 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
2fe80 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
2fe90 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
2fea0 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
2feb0 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
2fec0 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
2fed0 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
2fee0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2fef0 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
2ff00 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
2ff10 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
2ff20 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
2ff30 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
2ff40 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
2ff50 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
2ff60 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
2ff70 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
2ff80 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2ff90 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2ffa0 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
2ffb0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
2ffc0 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
2ffd0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2ffe0 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
2fff0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
30000 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
30010 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
30020 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
30030 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
30040 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
30050 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
30060 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
30070 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
30080 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
30090 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
300a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
300b0 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
300c0 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
300d0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
300e0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
300f0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51  undefined..*/.SQ
30100 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
30110 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
30120 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
30130 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
30140 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
30150 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
30160 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
30170 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
30180 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
30190 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
301a0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
301b0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
301c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
301d0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
301e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
301f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
30200 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
30210 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
30220 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
30230 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
30240 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
30250 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
30260 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
30270 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
30280 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
30290 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
302a0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
302b0 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
302c0 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
302d0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
302e0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
302f0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  3_stmt.**.** ^(T
30300 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
30310 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
30320 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
30330 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
30340 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
30350 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
30360 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
30370 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
30380 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
30390 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
303a0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
303b0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
303c0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
303d0 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
303e0 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
303f0 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
30400 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
30410 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
30420 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
30430 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
30440 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
30450 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
30460 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
30470 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
30480 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
30490 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
304a0 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
304b0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
304c0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
304d0 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
304e0 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
304f0 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
30500 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
30510 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
30520 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
30530 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
30540 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
30550 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
30560 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
30570 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
30580 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
30590 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
305a0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
305b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
305c0 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
305d0 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
305e0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
305f0 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
30600 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
30610 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
30620 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
30630 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
30640 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
30650 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
30660 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
30670 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
30680 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
30690 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
306a0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
306b0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
306c0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
306d0 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
306e0 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
306f0 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
30700 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
30710 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
30720 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
30730 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
30740 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
30750 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
30760 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
30770 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
30780 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
30790 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
307a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
307b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
307c0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
307d0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
307e0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
307f0 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
30800 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
30810 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
30820 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
30830 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30840 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
30850 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
30860 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
30870 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
30880 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
30890 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
308a0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
308b0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
308c0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
308d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
308e0 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
308f0 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
30900 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
30910 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
30920 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
30930 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
30940 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
30950 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
30960 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
30970 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
30980 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
30990 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
309a0 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
309b0 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
309c0 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
309d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
309e0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
309f0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
30a00 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
30a10 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
30a20 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
30a30 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
30a40 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
30a50 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
30a60 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
30a70 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
30a80 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
30a90 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
30aa0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
30ab0 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
30ac0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
30ad0 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65  **.** ^In the le
30ae0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
30af0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
30b00 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
30b10 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
30b20 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
30b30 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
30b40 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
30b50 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
30b60 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
30b70 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
30b80 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
30b90 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
30ba0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
30bb0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
30bc0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
30bd0 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  as well..**.** ^
30be0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
30bf0 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
30c00 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
30c10 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
30c20 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
30c30 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
30c40 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
30c50 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d    ^If the statem
30c60 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
30c70 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
30c80 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
30c90 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
30ca0 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
30cb0 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
30cc0 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
30cd0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
30ce0 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
30cf0 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e  occurs within an
30d00 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
30d10 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
30d20 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
30d30 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
30d40 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
30d50 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  inuing..**.** ^[
30d60 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
30d70 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
30d80 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
30d90 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
30da0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
30db0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
30dc0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
30dd0 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
30de0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
30df0 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
30e00 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
30e10 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
30e20 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
30e30 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
30e40 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
30e50 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  state..**.** ^If
30e60 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
30e70 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
30e80 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
30e90 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
30ea0 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
30eb0 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
30ec0 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
30ed0 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
30ee0 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
30ef0 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
30f00 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
30f10 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
30f20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
30f30 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
30f40 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
30f50 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
30f60 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
30f70 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
30f80 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52  *.** ^[SQLITE_ER
30f90 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
30fa0 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
30fb0 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
30fc0 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
30fd0 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
30fe0 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
30ff0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
31000 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
31010 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
31020 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
31030 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
31040 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
31050 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74  rmsg()]..** ^Wit
31060 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
31070 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
31080 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
31090 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
310a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
310b0 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
310c0 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
310d0 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
310e0 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
310f0 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
31100 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
31110 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
31120 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
31130 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68  tement].  ^In th
31140 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
31150 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
31160 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
31170 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
31180 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
31190 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
311a0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
311b0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
311c0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
311d0 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
311e0 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
311f0 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
31200 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
31210 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
31220 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
31230 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
31240 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
31250 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
31260 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
31270 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
31280 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
31290 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
312a0 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
312b0 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
312c0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
312d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
312e0 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
312f0 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
31300 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
31310 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
31320 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65  **.** For all ve
31330 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
31340 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75   up to and inclu
31350 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61  ding 3.6.23.1, a
31360 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
31370 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61  ite3_reset()] wa
31380 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72  s required after
31390 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
313a0 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
313b0 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  g.** other than 
313c0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66  [SQLITE_ROW] bef
313d0 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65  ore any subseque
313e0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  nt invocation of
313f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
31400 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20  ().  Failure to 
31410 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
31420 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
31430 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
31440 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72  reset()] would r
31450 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
31460 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
31470 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  rn from.** sqlit
31480 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20  e3_step().  But 
31490 61 66 74 65 72 20 5b 76 65 72 73 69 6f 6e 20 33  after [version 3
314a0 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74 65 6f  .6.23.1] ([dateo
314b0 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20  f:3.6.23.1],.** 
314c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
314d0 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
314e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
314f0 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
31500 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
31510 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
31520 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
31530 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
31540 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
31550 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
31560 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
31570 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
31580 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
31590 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
315a0 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
315b0 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
315c0 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
315d0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
315e0 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
315f0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
31600 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
31610 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
31620 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
31630 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
31640 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
31650 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
31660 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
31670 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
31680 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
31690 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
316a0 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
316b0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
316c0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
316d0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
316e0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
316f0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
31700 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
31710 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31720 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
31730 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
31740 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
31750 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
31760 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
31770 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
31780 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
31790 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
317a0 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
317b0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
317c0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
317d0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
317e0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
317f0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
31800 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
31810 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
31820 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
31830 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
31840 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
31850 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
31860 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
31870 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
31880 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
31890 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
318a0 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
318b0 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
318c0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
318d0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
318e0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
318f0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
31900 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
31910 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
31920 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
31930 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ended..*/.SQLITE
31940 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
31950 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
31960 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
31970 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
31980 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
31990 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48  sult set.** METH
319a0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
319b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
319c0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
319d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
319e0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
319f0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
31a00 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20  .** current row 
31a10 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
31a20 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
31a30 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
31a40 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61  ^If prepared sta
31a50 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f  tement P does no
31a60 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72  t have results r
31a70 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a  eady to return.*
31a80 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20  * (via calls to 
31a90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
31aa0 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  umn_int | sqlite
31ab0 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66  3_column_*()] of
31ac0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20  .** interfaces) 
31ad0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74  then sqlite3_dat
31ae0 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72  a_count(P) retur
31af0 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ns 0..** ^The sq
31b00 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
31b10 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f  (P) routine also
31b20 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20   returns 0 if P 
31b30 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
31b40 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  r..** ^The sqlit
31b50 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
31b60 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
31b70 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f   0 if the previo
31b80 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  us call to.** [s
31b90 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
31ba0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
31bb0 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71  _DONE].  ^The sq
31bc0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
31bd0 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  (P).** will retu
31be0 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70  rn non-zero if p
31bf0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
31c00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
31c10 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53  ) returned.** [S
31c20 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65  QLITE_ROW], exce
31c30 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f  pt in the case o
31c40 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e  f the [PRAGMA in
31c50 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d  cremental_vacuum
31c60 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c  ].** where it al
31c70 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72  ways returns zer
31c80 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65  o since each ste
31c90 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d  p of that multi-
31ca0 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72  step.** pragma r
31cb0 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73  eturns 0 columns
31cc0 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
31cd0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
31ce0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
31cf0 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )].*/.SQLITE_API
31d00 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74   int sqlite3_dat
31d10 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
31d20 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
31d30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
31d40 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
31d50 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
31d60 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
31d70 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
31d80 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
31d90 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
31da0 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
31db0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
31dc0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
31dd0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
31de0 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
31df0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
31e00 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
31e10 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
31e20 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
31e30 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
31e40 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
31e50 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
31e60 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
31e70 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
31e80 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
31e90 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
31ea0 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
31eb0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
31ec0 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
31ed0 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
31ee0 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
31ef0 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
31f00 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
31f10 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
31f20 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
31f30 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
31f40 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
31f50 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
31f60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
31f70 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
31f80 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
31f90 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
31fa0 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
31fb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
31fc0 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
31fd0 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
31fe0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
31ff0 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
32000 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
32010 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
32020 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
32030 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
32040 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
32050 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
32060 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
32070 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
32080 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
32090 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
320a0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
320b0 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
320c0 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
320d0 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
320e0 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
320f0 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
32100 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
32110 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
32120 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
32130 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
32140 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32150 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
32160 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
32170 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
32180 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
32190 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
321a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
321b0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
321c0 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
321d0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
321e0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
321f0 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
32200 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
32210 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
32220 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
32230 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
32240 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
32250 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
32260 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
32270 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
32280 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
32290 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
322a0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
322b0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
322c0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
322d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
322e0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
322f0 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
32300 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
32310 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
32320 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
32330 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
32340 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
32350 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
32360 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
32370 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
32380 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
32390 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
323a0 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
323b0 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
323c0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
323d0 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
323e0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
323f0 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
32400 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
32410 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
32420 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
32430 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
32440 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
32450 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
32460 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
32470 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
32480 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
32490 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
324a0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
324b0 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
324c0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
324d0 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
324e0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
324f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
32500 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
32510 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
32520 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
32530 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
32540 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
32550 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
32560 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
32570 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
32580 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
32590 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
325a0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
325b0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
325c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
325d0 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
325e0 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
325f0 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
32600 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
32610 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
32620 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
32630 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
32640 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
32650 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
32660 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
32670 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
32680 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
32690 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
326a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
326b0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
326c0 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
326d0 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
326e0 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
326f0 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
32700 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
32710 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
32720 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
32730 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
32740 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
32750 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
32760 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
32770 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
32780 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
32790 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
327a0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
327b0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
327c0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
327d0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
327e0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
327f0 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
32800 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
32810 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
32820 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
32830 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
32840 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
32850 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
32860 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
32870 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
32880 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
32890 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
328a0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
328b0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
328c0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
328d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
328e0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
328f0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
32900 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
32910 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32920 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
32930 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
32940 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
32950 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
32960 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
32970 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
32980 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
32990 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
329a0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
329b0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
329c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
329d0 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
329e0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
329f0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
32a00 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
32a10 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
32a20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32a30 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
32a40 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
32a50 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
32a60 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
32a70 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
32a80 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
32a90 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
32aa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32ab0 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
32ac0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
32ad0 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
32ae0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
32af0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
32b00 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
32b10 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
32b20 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
32b30 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
32b40 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
32b50 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
32b60 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
32b70 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
32b80 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
32b90 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
32ba0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
32bb0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
32bc0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
32bd0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
32be0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
32bf0 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
32c00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
32c10 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
32c20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
32c30 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
32c40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
32c50 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
32c60 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
32c70 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
32c80 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
32c90 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
32ca0 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
32cb0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
32cc0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
32cd0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
32ce0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
32cf0 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
32d00 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
32d10 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
32d20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
32d30 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
32d40 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
32d50 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
32d60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32d70 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
32d80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
32d90 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
32da0 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
32db0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
32dc0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
32dd0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
32de0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
32df0 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
32e00 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
32e10 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
32e20 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69  ..**.** <b>Warni
32e30 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a  ng:</b> ^The obj
32e40 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
32e50 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
32e60 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
32e70 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
32e80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
32e90 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74  ject.  In a mult
32ea0 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f  ithreaded enviro
32eb0 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70  nment,.** an unp
32ec0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
32ed0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
32ee0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73  y only be used s
32ef0 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73  afely with.** [s
32f00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
32f10 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
32f20 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
32f30 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
32f40 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
32f50 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
32f60 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
32f70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
32f80 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
32f90 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
32fa0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
32fb0 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
32fc0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
32fd0 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
32fe0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
32ff0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
33000 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
33010 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  )], the behavior
33020 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
33030 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  fe..**.** These 
33040 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
33050 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
33060 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
33070 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
33080 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
33090 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
330a0 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
330b0 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
330c0 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
330d0 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
330e0 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
330f0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
33100 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
33110 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
33120 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
33130 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
33140 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
33150 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
33160 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
33170 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
33180 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
33190 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
331a0 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
331b0 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
331c0 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
331d0 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
331e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
331f0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
33200 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
33210 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
33220 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
33230 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
33240 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
33250 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
33260 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
33270 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
33280 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
33290 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
332a0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
332b0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
332c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
332d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
332e0 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
332f0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
33300 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
33310 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
33320 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
33330 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
33340 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
33350 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
33360 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
33370 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
33380 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
33390 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
333a0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
333b0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
333c0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
333d0 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
333e0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
333f0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
33400 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
33410 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
33420 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
33430 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
33440 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
33450 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64   BLOB.** <tr><td
33460 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
33470 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
33480 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
33490 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
334a0 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
334b0 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
334c0 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
334d0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
334e0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
334f0 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
33500 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
33510 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
33520 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
33530 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
33540 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
33550 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
33560 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
33570 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
33580 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
33590 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
335a0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
335b0 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
335c0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
335d0 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ote>)^.**.** Not
335e0 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
335f0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
33600 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
33610 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
33620 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
33630 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
33640 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
33650 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
33660 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
33670 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
33680 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
33690 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
336a0 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
336b0 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
336c0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
336d0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
336e0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
336f0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
33700 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
33710 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
33720 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
33730 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
33740 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
33750 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
33760 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
33770 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
33780 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
33790 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
337a0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
337b0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
337c0 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
337d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
337e0 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
337f0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
33800 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
33810 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
33820 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
33830 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
33840 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
33850 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
33860 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
33870 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
33880 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
33890 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
338a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
338b0 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
338c0 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
338d0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
338e0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
338f0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  .</li>.** </ul>.
33900 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f  **.** ^Conversio
33910 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
33920 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
33930 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
33940 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
33950 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
33960 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
33970 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
33980 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
33990 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
339a0 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
339b0 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e   pointer referen
339c0 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65  ces will have be
339d0 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
339e0 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
339f0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
33a00 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
33a10 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
33a20 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
33a30 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
33a40 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
33a50 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
33a60 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
33a70 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
33a80 2a 20 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c  * The safest pol
33a90 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
33aa0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
33ab0 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
33ac0 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
33ad0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
33ae0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
33af0 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
33b00 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
33b10 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
33b20 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
33b30 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
33b40 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
33b50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
33b60 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
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 66 6f 6c 6c 6f 77 65 64  ext16() followed
33b90 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
33ba0 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
33bb0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
33bc0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
33bd0 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
33be0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33bf0 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
33c00 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
33c10 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
33c20 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
33c30 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
33c40 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
33c50 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
33c60 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
33c70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
33c80 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
33c90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
33ca0 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
33cb0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
33cc0 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
33cd0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
33ce0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
33cf0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
33d00 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
33d10 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
33d20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33d30 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
33d40 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
33d50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33d60 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
33d70 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
33d80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
33d90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
33da0 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
33db0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
33dc0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
33dd0 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
33de0 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
33df0 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
33e00 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
33e10 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
33e20 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
33e30 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
33e40 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
33e50 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
33e60 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
33e70 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
33e80 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
33e90 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  Do <em>not</em> 
33ea0 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
33eb0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  s returned.** fr
33ec0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
33ed0 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
33ee0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
33ef0 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
33f00 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
33f10 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
33f20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
33f30 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
33f40 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
33f50 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
33f60 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
33f70 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
33f80 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
33f90 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
33fa0 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
33fb0 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
33fc0 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
33fd0 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
33fe0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
33ff0 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
34000 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
34010 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
34020 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
34030 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
34040 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
34050 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
34060 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
34070 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
34080 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
34090 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
340a0 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
340b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
340c0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
340d0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
340e0 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
340f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
34100 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64  l);.SQLITE_API d
34110 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
34120 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
34130 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
34140 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
34150 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
34160 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
34170 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
34180 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
34190 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
341a0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
341b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
341c0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
341d0 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67  _API const unsig
341e0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
341f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
34200 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
34210 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
34220 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
34230 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
34240 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
34250 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
34260 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
34270 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
34280 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
34290 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
342a0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76  TE_API sqlite3_v
342b0 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
342c0 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
342d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
342e0 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
342f0 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
34300 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
34310 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53  nt Object.** DES
34320 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
34330 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
34340 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
34350 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
34360 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
34370 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
34380 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
34390 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
343a0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
343b0 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
343c0 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
343d0 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  s.** or if the s
343e0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
343f0 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
34400 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
34410 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
34420 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
34430 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
34440 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
34450 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
34460 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
34470 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
34480 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
34490 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
344a0 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
344b0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
344c0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
344d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
344e0 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
344f0 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
34500 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
34510 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
34520 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
34530 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
34540 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
34550 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
34560 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
34570 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
34580 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
34590 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
345a0 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
345b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
345c0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
345d0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
345e0 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
345f0 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
34600 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
34610 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
34620 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
34630 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
34640 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
34650 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
34660 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
34670 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
34680 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
34690 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
346a0 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
346b0 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
346c0 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
346d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
346e0 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
346f0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
34700 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
34710 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
34720 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
34730 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
34740 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
34750 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
34760 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
34770 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
34780 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
34790 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
347a0 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
347b0 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
347c0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
347d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
347e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
347f0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
34800 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
34810 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
34820 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48  t Object.** METH
34830 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
34840 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
34850 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
34860 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
34870 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
34880 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
34890 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20   object back to 
348a0 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
348b0 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
348c0 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e  e-executed..** ^
348d0 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
348e0 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
348f0 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
34900 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
34910 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
34920 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
34930 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
34940 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
34950 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
34960 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
34970 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
34980 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
34990 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
349a0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
349b0 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
349c0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
349d0 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63  tement] S.** bac
349e0 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
349f0 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
34a00 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  m..**.** ^If the
34a10 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
34a20 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
34a30 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
34a40 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
34a50 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
34a60 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
34a70 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
34a80 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74  .** or if [sqlit
34a90 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
34aa0 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
34ab0 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
34ac0 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * then [sqlite3_
34ad0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
34ae0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
34af0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
34b00 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
34b10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
34b20 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
34b30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34b40 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
34b50 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
34b60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34b70 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
34b80 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
34b90 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
34ba0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
34bb0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
34bc0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
34bd0 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f   the values.** o
34be0 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
34bf0 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
34c00 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
34c10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
34c20 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
34c30 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
34c40 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
34c50 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
34c60 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
34c70 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
34c80 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
34c90 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
34ca0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
34cb0 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
34cc0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
34cd0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
34ce0 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
34cf0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
34d00 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
34d10 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
34d20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
34d30 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
34d40 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
34d50 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
34d60 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
34d70 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
34d80 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
34d90 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
34da0 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
34db0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
34dc0 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
34dd0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
34de0 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
34df0 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
34e00 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
34e10 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
34e20 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
34e30 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
34e40 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
34e50 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
34e60 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
34e70 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
34e80 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
34e90 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
34ea0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
34eb0 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
34ec0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
34ed0 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
34ee0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
34ef0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
34f00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34f10 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
34f20 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
34f30 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
34f40 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
34f50 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
34f60 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
34f70 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
34f80 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
34f90 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
34fa0 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
34fb0 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
34fc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34fd0 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
34fe0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
34ff0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
35000 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
35010 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
35020 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
35030 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
35040 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
35050 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
35060 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
35070 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
35080 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
35090 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
350a0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
350b0 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
350c0 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
350d0 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
350e0 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
350f0 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
35100 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
35110 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
35120 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
35130 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
35140 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
35150 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
35160 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
35170 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
35180 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
35190 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
351a0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
351b0 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
351c0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
351d0 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
351e0 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
351f0 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
35200 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
35210 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
35220 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
35230 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
35240 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
35250 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
35260 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
35270 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
35280 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
35290 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
352a0 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
352b0 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
352c0 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
352d0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
352e0 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
352f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
35300 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
35310 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
35320 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
35330 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
35340 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
35350 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
35360 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
35370 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70  meters.  The app
35380 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
35390 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74  set this paramet
353a0 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  er to.** [SQLITE
353b0 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65  _UTF16LE] if the
353c0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
353d0 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
353e0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
353f0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20  lue_text16le()] 
35400 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20  on an input, or 
35410 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
35420 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   if the.** imple
35430 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
35440 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  s [sqlite3_value
35450 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20  _text16be()] on 
35460 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20  an input, or.** 
35470 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69  [SQLITE_UTF16] i
35480 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
35490 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73  _text16()] is us
354a0 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ed, or [SQLITE_U
354b0 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73  TF8].** otherwis
354c0 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51  e.  ^The same SQ
354d0 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  L function may b
354e0 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
354f0 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e  tiple times usin
35500 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70  g.** different p
35510 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
35520 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69  codings, with di
35530 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  fferent implemen
35540 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65  tations for.** e
35550 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ach encoding..**
35560 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
35570 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
35580 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
35590 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
355a0 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
355b0 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
355c0 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
355d0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
355e0 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
355f0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  n..**.** ^The fo
35600 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d  urth parameter m
35610 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65  ay optionally be
35620 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49   ORed with [SQLI
35630 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
35640 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74  ].** to signal t
35650 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hat the function
35660 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
35670 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73  urn the same res
35680 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65  ult given.** the
35690 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74   same inputs wit
356a0 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  hin a single SQL
356b0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73   statement.  Mos
356c0 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
356d0 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69  are.** determini
356e0 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74  stic.  The built
356f0 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53  -in [random()] S
35700 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  QL function is a
35710 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a  n example of a.*
35720 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  * function that 
35730 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69  is not determini
35740 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74  stic.  The SQLit
35750 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20  e query planner 
35760 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65  is able to.** pe
35770 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c  rform additional
35780 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f   optimizations o
35790 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20  n deterministic 
357a0 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73  functions, so us
357b0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  e.** of the [SQL
357c0 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
357d0 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d  C] flag is recom
357e0 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73  mended where pos
357f0 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  sible..**.** ^(T
35800 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
35810 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
35820 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
35830 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35840 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
35850 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
35860 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
35870 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
35880 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
35890 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
358a0 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
358b0 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
358c0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
358d0 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
358e0 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
358f0 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
35900 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
35910 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
35920 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
35930 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
35940 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
35950 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
35960 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
35970 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
35980 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
35990 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
359a0 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
359b0 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
359c0 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
359d0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
359e0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
359f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35a00 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
35a10 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
35a20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
35a30 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
35a40 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
35a50 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
35a60 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
35a70 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
35a80 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
35a90 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
35aa0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
35ab0 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
35ac0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
35ad0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35ae0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
35af0 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
35b00 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
35b10 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
35b20 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
35b30 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
35b40 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
35b50 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
35b60 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
35b70 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
35b80 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
35b90 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
35ba0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
35bb0 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
35bc0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
35bd0 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
35be0 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
35bf0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35c00 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
35c10 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
35c20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
35c30 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
35c40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
35c50 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
35c60 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
35c70 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
35c80 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
35c90 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
35ca0 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
35cb0 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
35cc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
35cd0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
35ce0 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
35cf0 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
35d00 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
35d10 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
35d20 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
35d30 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
35d40 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
35d50 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
35d60 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
35d70 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
35d80 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
35d90 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
35da0 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
35db0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
35dc0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
35dd0 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
35de0 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
35df0 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
35e00 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
35e10 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
35e20 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
35e30 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
35e40 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
35e50 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
35e60 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
35e70 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
35e80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35e90 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
35ea0 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
35eb0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
35ec0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
35ed0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
35ee0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
35ef0 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
35f00 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
35f10 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
35f20 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
35f30 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
35f40 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
35f50 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
35f60 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
35f70 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
35f80 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
35f90 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
35fa0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
35fb0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
35fc0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
35fd0 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
35fe0 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
35ff0 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
36000 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
36010 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
36020 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
36030 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
36040 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
36050 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
36060 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
36070 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
36080 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
36090 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
360a0 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
360b0 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
360c0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
360d0 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
360e0 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
360f0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
36100 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
36110 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
36120 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
36130 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
36140 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
36150 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
36160 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
36170 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
36180 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
36190 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
361a0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
361b0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
361c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
361d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
361e0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
361f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36200 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
36210 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
36220 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
36230 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51  _context*).);.SQ
36240 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
36250 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
36260 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
36270 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
36280 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
36290 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
362a0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
362b0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
362c0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
362d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
362e0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
362f0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
36300 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
36310 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
36320 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
36330 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
36340 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
36350 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
36360 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36370 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
36380 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
36390 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
363a0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
363b0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
363c0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
363d0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
363e0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
363f0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
36400 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
36410 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
36420 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
36430 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
36440 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
36450 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
36460 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
36470 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
36480 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36490 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
364a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
364b0 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
364c0 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
364d0 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
364e0 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
364f0 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
36500 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
36510 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
36520 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20  TF8           1 
36530 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35     /* IMP: R-375
36540 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66  14-35566 */.#def
36550 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
36560 4c 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f  LE        2    /
36570 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33  * IMP: R-03371-3
36580 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20  7637 */.#define 
36590 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
365a0 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d        3    /* IM
365b0 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34  P: R-51971-34154
365c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
365d0 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
365e0 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
365f0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
36600 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
36610 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
36620 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61   5    /* Depreca
36630 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ted */.#define S
36640 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
36650 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
36660 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36670 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
36680 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
36690 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a  unction Flags.**
366a0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
366b0 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20  nts may be ORed 
366c0 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68  together with th
366d0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  e .** [SQLITE_UT
366e0 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74  F8 | preferred t
366f0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73  ext encoding] as
36700 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
36710 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ment.** to [sqli
36720 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
36730 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
36740 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
36750 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
36760 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
36770 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ction_v2()]..*/.
36780 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
36790 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20  ETERMINISTIC    
367a0 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  0x800../*.** CAP
367b0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
367c0 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
367d0 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
367e0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
367f0 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
36800 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
36810 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
36820 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
36830 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
36840 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
36850 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
36860 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
36870 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
36880 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
36890 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
368a0 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
368b0 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63  nctions.  To enc
368c0 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65  ourage programme
368d0 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  rs to avoid.** t
368e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
368f0 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c  we will not expl
36900 61 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f  ain what they do
36910 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
36920 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41  ITE_OMIT_DEPRECA
36930 54 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  TED.SQLITE_API S
36940 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
36950 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
36960 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
36970 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
36980 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
36990 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
369a0 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64   sqlite3_expired
369b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
369c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
369d0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
369e0 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
369f0 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
36a00 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
36a10 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
36a20 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
36a30 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
36a40 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
36a50 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
36a60 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
36a70 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
36a80 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
36a90 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  up(void);.SQLITE
36aa0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
36ab0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
36ac0 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
36ad0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
36ae0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
36af0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
36b00 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71          void*,sq
36b10 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
36b20 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
36b30 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
36b40 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45  SQL Values.** ME
36b50 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61  THOD: sqlite3_va
36b60 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  lue.**.** The C-
36b70 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
36b80 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
36b90 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
36ba0 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
36bb0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
36bc0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
36bd0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
36be0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
36bf0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
36c00 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 20   or aggregate.  
36c10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
36c20 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
36c30 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
36c40 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
36c50 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
36c60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
36c70 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
36c80 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
36c90 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
36ca0 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
36cb0 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
36cc0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
36cd0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
36ce0 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64  ates..** The 3rd
36cf0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
36d00 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
36d10 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
36d20 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
36d30 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
36d40 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
36d50 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
36d60 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36d70 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
36d80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
36d90 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
36da0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
36db0 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
36dc0 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
36dd0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
36de0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
36df0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
36e00 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
36e10 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
36e20 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36e30 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
36e40 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
36e50 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
36e60 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
36e70 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
36e80 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
36e90 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
36ea0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
36eb0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
36ec0 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
36ed0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
36ee0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
36ef0 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
36f00 20 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74   that these rout
36f10 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
36f20 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
36f30 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36f40 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
36f50 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
36f60 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
36f70 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
36f80 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
36f90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36fa0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
36fb0 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
36fc0 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
36fd0 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
36fe0 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
36ff0 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
37000 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a  achine.  ^The.**
37010 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
37020 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
37030 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
37040 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
37050 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
37060 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
37070 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
37080 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
37090 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
370a0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
370b0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
370c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
370d0 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
370e0 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
370f0 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
37100 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
37110 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
37120 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
37130 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
37140 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
37150 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
37160 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
37170 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
37180 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
37190 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
371a0 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
371b0 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
371c0 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
371d0 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
371e0 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
371f0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
37200 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
37210 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
37220 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
37230 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
37240 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
37250 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
37260 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
37270 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
37280 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
37290 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
372a0 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
372b0 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
372c0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
372d0 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
372e0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
372f0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
37300 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
37310 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
37320 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
37330 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
37340 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
37350 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
37360 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
37370 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
37380 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
37390 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
373a0 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
373b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
373c0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
373d0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
373e0 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
373f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
37400 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
37410 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
37420 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51  arameters..*/.SQ
37430 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
37440 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
37450 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
37460 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
37470 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
37480 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
37490 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
374a0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
374b0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
374c0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
374d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f  );.SQLITE_API do
374e0 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
374f0 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
37500 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
37510 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
37520 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69  3_value_int(sqli
37530 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
37540 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
37550 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
37560 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
37570 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
37580 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69  E_API const unsi
37590 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
375a0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
375b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
375c0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
375d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
375e0 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74  lue_text16(sqlit
375f0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
37600 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
37610 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
37620 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
37630 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
37640 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
37650 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
37660 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
37670 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
37680 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
37690 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
376a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
376b0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
376c0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
376d0 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
376e0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
376f0 41 50 49 33 52 45 46 3a 20 46 69 6e 64 69 6e 67  API3REF: Finding
37700 20 54 68 65 20 53 75 62 74 79 70 65 20 4f 66 20   The Subtype Of 
37710 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45  SQL Values.** ME
37720 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61  THOD: sqlite3_va
37730 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  lue.**.** The sq
37740 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74  lite3_value_subt
37750 79 70 65 28 56 29 20 66 75 6e 63 74 69 6f 6e 20  ype(V) function 
37760 72 65 74 75 72 6e 73 20 74 68 65 20 73 75 62 74  returns the subt
37770 79 70 65 20 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61  ype for.** an [a
37780 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
37790 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  ed SQL function]
377a0 20 61 72 67 75 6d 65 6e 74 20 56 2e 20 20 54 68   argument V.  Th
377b0 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 69 6e 66  e subtype.** inf
377c0 6f 72 6d 61 74 69 6f 6e 20 63 61 6e 20 62 65 20  ormation can be 
377d0 75 73 65 64 20 74 6f 20 70 61 73 73 20 61 20 6c  used to pass a l
377e0 69 6d 69 74 65 64 20 61 6d 6f 75 6e 74 20 6f 66  imited amount of
377f0 20 63 6f 6e 74 65 78 74 20 66 72 6f 6d 0a 2a 2a   context from.**
37800 20 6f 6e 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   one SQL functio
37810 6e 20 74 6f 20 61 6e 6f 74 68 65 72 2e 20 20 55  n to another.  U
37820 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
37830 72 65 73 75 6c 74 5f 73 75 62 74 79 70 65 28 29  result_subtype()
37840 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  ].** routine to 
37850 73 65 74 20 74 68 65 20 73 75 62 74 79 70 65 20  set the subtype 
37860 66 6f 72 20 74 68 65 20 72 65 74 75 72 6e 20 76  for the return v
37870 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 66  alue of an SQL f
37880 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53  unction..**.** S
37890 51 4c 69 74 65 20 6d 61 6b 65 73 20 6e 6f 20 75  QLite makes no u
378a0 73 65 20 6f 66 20 73 75 62 74 79 70 65 20 69 74  se of subtype it
378b0 73 65 6c 66 2e 20 20 49 74 20 6d 65 72 65 6c 79  self.  It merely
378c0 20 70 61 73 73 65 73 20 74 68 65 20 73 75 62 74   passes the subt
378d0 79 70 65 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ype.** from the 
378e0 72 65 73 75 6c 74 20 6f 66 20 6f 6e 65 20 5b 61  result of one [a
378f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
37900 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  ed SQL function]
37910 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6e 70   into the.** inp
37920 75 74 20 6f 66 20 61 6e 6f 74 68 65 72 2e 0a 2a  ut of another..*
37930 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 75 6e 73  /.SQLITE_API uns
37940 69 67 6e 65 64 20 69 6e 74 20 73 71 6c 69 74 65  igned int sqlite
37950 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28  3_value_subtype(
37960 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37970 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37980 3a 20 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20  : Copy And Free 
37990 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45  SQL Values.** ME
379a0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61  THOD: sqlite3_va
379b0 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  lue.**.** ^The s
379c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
379d0 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  (V) interface ma
379e0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
379f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
37a00 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e  ].** object D an
37a10 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
37a20 74 65 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79  ter to that copy
37a30 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
37a40 5f 76 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64  _value] returned
37a50 0a 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63  .** is a [protec
37a60 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
37a70 65 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69  e] object even i
37a80 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e  f the input is n
37a90 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ot..** ^The sqli
37aa0 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29  te3_value_dup(V)
37ab0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
37ac0 6e 73 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20  ns NULL if V is 
37ad0 4e 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20  NULL or if a.** 
37ae0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
37af0 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  n fails..**.** ^
37b00 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
37b10 65 5f 66 72 65 65 28 56 29 20 69 6e 74 65 72 66  e_free(V) interf
37b20 61 63 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71  ace frees an [sq
37b30 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
37b40 65 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ect.** previousl
37b50 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
37b60 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  [sqlite3_value_d
37b70 75 70 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73  up()].  ^If V is
37b80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
37b90 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
37ba0 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73  value_free(V) is
37bb0 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
37bc0 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  p..*/.SQLITE_API
37bd0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
37be0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
37bf0 70 28 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  p(const sqlite3_
37c00 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
37c10 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
37c20 5f 76 61 6c 75 65 5f 66 72 65 65 28 73 71 6c 69  _value_free(sqli
37c30 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
37c40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
37c50 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
37c60 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a  unction Context.
37c70 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
37c80 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  e3_context.**.**
37c90 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   Implementations
37ca0 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51   of aggregate SQ
37cb0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20  L functions use 
37cc0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
37cd0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
37ce0 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  ry for storing t
37cf0 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  heir state..**.*
37d00 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
37d10 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67  e the sqlite3_ag
37d20 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
37d30 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20  C,N) routine is 
37d40 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61  called .** for a
37d50 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
37d60 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20  egate function, 
37d70 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61  SQLite.** alloca
37d80 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c  tes N of memory,
37d90 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74   zeroes out that
37da0 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74   memory, and ret
37db0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
37dc0 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d  * to the new mem
37dd0 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20  ory. ^On second 
37de0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
37df0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
37e00 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
37e10 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73  text() for the s
37e20 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
37e30 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c  nction instance,
37e40 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66  .** the same buf
37e50 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
37e60 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67    Sqlite3_aggreg
37e70 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73  ate_context() is
37e80 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c   normally.** cal
37e90 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  led once for eac
37ea0 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  h invocation of 
37eb0 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61  the xStep callba
37ec0 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a  ck and then one.
37ed0 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65  ** last time whe
37ee0 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
37ef0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
37f00 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77  .  ^(When no row
37f10 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67  s match.** an ag
37f20 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74  gregate query, t
37f30 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62  he xStep() callb
37f40 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65  ack of the aggre
37f50 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gate function.**
37f60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
37f70 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20  is never called 
37f80 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20  and xFinal() is 
37f90 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f  called exactly o
37fa0 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  nce..** In those
37fb0 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f   cases, sqlite3_
37fc0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
37fd0 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c  t() might be cal
37fe0 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66  led for the.** f
37ff0 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77  irst time from w
38000 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29  ithin xFinal().)
38010 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
38020 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
38030 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
38040 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ine returns a NU
38050 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77  LL pointer .** w
38060 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64  hen first called
38070 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68   if N is less th
38080 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
38090 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f  ero or if a memo
380a0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65  ry.** allocate e
380b0 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
380c0 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20  ** ^(The amount 
380d0 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74  of space allocat
380e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67  ed by sqlite3_ag
380f0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
38100 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72  C,N) is.** deter
38110 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70  mined by the N p
38120 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73  arameter on firs
38130 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  t successful cal
38140 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65  l.  Changing the
38150 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69  .** value of N i
38160 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
38170 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  l to sqlite3_agg
38180 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
38190 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73   within.** the s
381a0 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
381b0 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20  nction instance 
381c0 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20  will not resize 
381d0 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
381e0 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74  location.)^  Wit
381f0 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63  hin the xFinal c
38200 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63  allback, it is c
38210 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a  ustomary to set.
38220 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20  ** N=0 in calls 
38230 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
38240 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
38250 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a  ) so that no .**
38260 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72   pointless memor
38270 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63  y allocations oc
38280 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  cur..**.** ^SQLi
38290 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
382a0 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72   frees the memor
382b0 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a  y allocated by .
382c0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
382d0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
382e0 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
382f0 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  e query conclude
38300 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
38310 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  st parameter mus
38320 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  t be a copy of t
38330 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
38340 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
38350 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
38360 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
38370 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
38380 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46   the xStep or xF
38390 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f  inal callback ro
383a0 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
383b0 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
383c0 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
383d0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
383e0 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
383f0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
38400 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
38410 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
38420 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
38430 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
38440 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
38450 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
38460 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
38470 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
38480 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
38490 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
384a0 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
384b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
384c0 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
384d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
384e0 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
384f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
38500 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
38510 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
38520 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
38530 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
38540 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
38550 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
38560 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
38570 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
38580 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
38590 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
385a0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
385b0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
385c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
385d0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
385e0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
385f0 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
38600 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
38610 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
38620 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
38630 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
38640 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
38650 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
38660 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
38670 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
38680 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
38690 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
386a0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72  e Connection For
386b0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45   Functions.** ME
386c0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f  THOD: sqlite3_co
386d0 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ntext.**.** ^The
386e0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
386f0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
38700 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
38710 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
38720 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
38730 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
38740 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
38750 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).**