/ Hex Artifact Content
Login

Artifact a41f8ca1bb1e20bcd40c75f238cc1c622295e60b6a88f89e76251759cba7d125:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65  LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 5b 76 65 72 73 69 6f  ** Since [versio
0f00: 6e 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65  n 3.6.18] ([date
0f10: 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a  of:3.6.18]), .**
0f20: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
0f30: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
0f40: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
0f50: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
0f60: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
0f70: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
0f80: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0f90: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
0fa0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
0fb0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
0fc0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
0fd0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
0fe0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
0ff0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
1000: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
1010: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
1020: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
1030: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
1040: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
1050: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
1060: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
1070: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
1080: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 20  -in (UTC) and a 
1090: 53 48 41 31 0a 2a 2a 20 6f 72 20 53 48 41 33 2d  SHA1.** or SHA3-
10a0: 32 35 36 20 68 61 73 68 20 6f 66 20 74 68 65 20  256 hash of the 
10b0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
10c0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
10d0: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
10e0: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
10f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1100: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1110: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1120: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1130: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1140: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1150: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1160: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
1170: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
1180: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1190: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
11a0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
11b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11c0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
11d0: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
11e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11f0: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1200: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1210: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1220: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71  lite3_version sq
1230: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a  lite3_sourceid.*
1240: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72  *.** These inter
1250: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68  faces provide th
1260: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
1270: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54  on as the [SQLIT
1280: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b  E_VERSION],.** [
1290: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
12a0: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c  UMBER], and [SQL
12b0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
12c0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
12d0: 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20  cros.** but are 
12e0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
12f0: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
1300: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
1310: 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69  r file.  ^(Cauti
1320: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65  ous.** programme
1330: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65  rs might include
1340: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
1350: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70  ents in their ap
1360: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
1370: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75  verify that valu
1380: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  es returned by t
1390: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
13a0: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73  match the macros
13b0: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65   in.** the heade
13c0: 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75  r, and thus ensu
13d0: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c  re that the appl
13e0: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f  ication is.** co
13f0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63  mpiled with matc
1400: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64  hing library and
1410: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a   header files..*
1420: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1430: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74  ><pre>.** assert
1440: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  ( sqlite3_libver
1450: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53  sion_number()==S
1460: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1470: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72  MBER );.** asser
1480: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1490: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
14a0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d  ITE_SOURCE_ID)==
14b0: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20  0 );.** assert( 
14c0: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c  strcmp(sqlite3_l
14d0: 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49  ibversion(),SQLI
14e0: 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29  TE_VERSION)==0 )
14f0: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1500: 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1510: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65   ^The sqlite3_ve
1520: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
1530: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73  onstant contains
1540: 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51   the text of [SQ
1550: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a  LITE_VERSION].**
1560: 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71   macro.  ^The sq
1570: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1580: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
1590: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
15a0: 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73   the.** to the s
15b0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
15c0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
15d0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  .  The sqlite3_l
15e0: 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66  ibversion().** f
15f0: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
1600: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44  ded for use in D
1610: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73  LLs since DLL us
1620: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e  ers usually do n
1630: 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63  ot have.** direc
1640: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
1650: 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74  ng constants wit
1660: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54  hin the DLL.  ^T
1670: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  he.** sqlite3_li
1680: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1690: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
16a0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71  ns an integer eq
16b0: 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ual to.** [SQLIT
16c0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
16d0: 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
16e0: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63  _sourceid() func
16f0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a  tion returns .**
1700: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1710: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
1720: 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74  whose value is t
1730: 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a  he same as the .
1740: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  ** [SQLITE_SOURC
1750: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
1760: 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  ssor macro..**.*
1770: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1780: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
1790: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
17a0: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  e_id()]..*/.SQLI
17b0: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20  TE_EXTERN const 
17c0: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
17d0: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68  sion[];.const ch
17e0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
17f0: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f  ersion(void);.co
1800: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1810: 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29  3_sourceid(void)
1820: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  ;.int sqlite3_li
1830: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1840: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
1850: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1860: 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61   Library Compila
1870: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61  tion Options Dia
1880: 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e  gnostics.**.** ^
1890: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
18a0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
18b0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
18c0: 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64  s 0 or 1 .** ind
18d0: 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20  icating whether 
18e0: 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70  the specified op
18f0: 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64  tion was defined
1900: 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20   at .** compile 
1910: 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49  time.  ^The SQLI
1920: 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62  TE_ prefix may b
1930: 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  e omitted from t
1940: 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61  he .** option na
1950: 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c  me passed to sql
1960: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1970: 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a  on_used().  .**.
1980: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
19a0: 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c  t() function all
19b0: 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a  ows iterating.**
19c0: 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f   over the list o
19d0: 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77  f options that w
19e0: 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63  ere defined at c
19f0: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a  ompile time by.*
1a00: 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20  * returning the 
1a10: 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d  N-th compile tim
1a20: 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e  e option string.
1a30: 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f    ^If N is out o
1a40: 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69  f range,.** sqli
1a50: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1a60: 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20  n_get() returns 
1a70: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1a80: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a   ^The SQLITE_ .*
1a90: 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74  * prefix is omit
1aa0: 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72  ted from any str
1ab0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1ac0: 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d   .** sqlite3_com
1ad0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ae0: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74  ..**.** ^Support
1af0: 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73   for the diagnos
1b00: 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71  tic functions sq
1b10: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1b20: 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e  ion_used().** an
1b30: 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  d sqlite3_compil
1b40: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61  eoption_get() ma
1b50: 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20  y be omitted by 
1b60: 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a  specifying the .
1b70: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  ** [SQLITE_OMIT_
1b80: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1b90: 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63  AGS] option at c
1ba0: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a  ompile time..**.
1bb0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c  ** See also: SQL
1bc0: 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69   functions [sqli
1bd0: 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  te_compileoption
1be0: 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1bf0: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f  [sqlite_compileo
1c00: 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64  ption_get()] and
1c10: 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70   the [compile_op
1c20: 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a  tions pragma]..*
1c30: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
1c40: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54  _OMIT_COMPILEOPT
1c50: 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73 71  ION_DIAGS.int sq
1c60: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c70: 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63  ion_used(const c
1c80: 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a  har *zOptName);.
1c90: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1ca0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1cb0: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
1cc0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1cd0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
1ce0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
1cf0: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
1d00: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d10: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
1d20: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1d30: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
1d40: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
1d50: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1d60: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
1d70: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
1d80: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
1d90: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
1da0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
1db0: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
1dc0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
1dd0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1de0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1df0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1e00: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1e10: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1e20: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
1e30: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
1e40: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1e50: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1e60: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
1e70: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1e80: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
1e90: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
1ea0: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1eb0: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1ec0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1ed0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1ee0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
1ef0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
1f00: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
1f10: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
1f20: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
1f30: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
1f40: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1f50: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1f60: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
1f70: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
1f80: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
1f90: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
1fa0: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
1fb0: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
1fc0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1fd0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
1fe0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
1ff0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
2000: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
2010: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
2020: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
2030: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
2040: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
2050: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
2060: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
2070: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
2080: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
2090: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
20a0: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
20b0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
20c0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
20d0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
20e0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
20f0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
2100: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
2110: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
2120: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
2130: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
2140: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2150: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
2160: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
2170: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
2180: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
2190: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
21a0: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
21b0: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
21c0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
21d0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
21e0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
21f0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2200: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
2210: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2220: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
2230: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2240: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e  _SERIALIZED].  ^
2250: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
2260: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
2270: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2280: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2290: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
22a0: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
22b0: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
22c0: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
22d0: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
22e0: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
22f0: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2300: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2310: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2320: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
2330: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2340: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
2350: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
2360: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2370: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
2380: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2390: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
23a0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
23b0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
23c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
23d0: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
23e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
23f0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2400: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2410: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2420: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
2430: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2440: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
2450: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
2460: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
2470: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
2480: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2490: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
24a0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
24b0: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
24c0: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
24d0: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
24e0: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
24f0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2500: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2510: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2520: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2530: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
2540: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
2550: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
2560: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2570: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
2580: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2590: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
25a0: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
25b0: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
25c0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
25d0: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
25e0: 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b  prepare_v3()], [
25f0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2600: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
2610: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
2620: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
2630: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
2640: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
2650: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
2660: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
2670: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2680: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
2690: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
26a0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
26b0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
26c0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
26d0: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
26e0: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
26f0: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
2700: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
2710: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
2720: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
2730: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
2740: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
2750: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
2760: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
2770: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2780: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
2790: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
27a0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
27b0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
27c0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
27d0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
27e0: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
27f0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
2800: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
2810: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
2820: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
2830: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
2840: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
2850: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2860: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
2870: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2880: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
2890: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
28a0: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
28b0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
28c0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
28d0: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
28e0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
28f0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
2900: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
2910: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
2920: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
2930: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
2940: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2950: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2960: 65 5f 69 6e 74 36 34 3b 0a 23 20 69 66 64 65 66  e_int64;.# ifdef
2970: 20 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54   SQLITE_UINT64_T
2980: 59 50 45 0a 20 20 20 20 74 79 70 65 64 65 66 20  YPE.    typedef 
2990: 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54 59  SQLITE_UINT64_TY
29a0: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
29b0: 3b 0a 23 20 65 6c 73 65 20 20 0a 20 20 20 20 74  ;.# else  .    t
29c0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
29d0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
29e0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
29f0: 0a 23 20 65 6e 64 69 66 0a 23 65 6c 69 66 20 64  .# endif.#elif d
2a00: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2a10: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2a20: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2a30: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2a40: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2a50: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2a60: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2a70: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
2a80: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
2a90: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
2aa0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2ab0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
2ac0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2ad0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2ae0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2af0: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2b00: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2b10: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2b20: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2b30: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2b40: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2b50: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2b60: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2b70: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
2b80: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
2b90: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
2ba0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
2bb0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
2bc0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
2bd0: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2be0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2bf0: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2c00: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45  Connection.** DE
2c10: 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2c20: 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
2c30: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
2c40: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2c50: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
2c60: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
2c70: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
2c80: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
2c90: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2ca0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2cb0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
2cc0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2cd0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ce0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2cf0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2d00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2d10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2d20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2d30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2d40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2d50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2d60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2d70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2d90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2da0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2db0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2dc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2dd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2de0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2df0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2e00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2e10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2e20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2e30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2e40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2e50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72  ements.** and/or
2e60: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2e70: 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65  te3_backups, the
2e80: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
2e90: 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65  onnection become
2ea0: 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65  s.** an unusable
2eb0: 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20   "zombie" which 
2ec0: 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
2ed0: 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ly be deallocate
2ee0: 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61  d when the.** la
2ef0: 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
2f00: 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a  ement is finaliz
2f10: 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73  ed or the last s
2f20: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73  qlite3_backup is
2f30: 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54  .** finished.  T
2f40: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  he sqlite3_close
2f50: 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
2f60: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
2f70: 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74  use with.** host
2f80: 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20   languages that 
2f90: 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c  are garbage coll
2fa0: 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65  ected, and where
2fb0: 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68   the order in wh
2fc0: 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f  ich.** destructo
2fd0: 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73  rs are called is
2fe0: 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a   arbitrary..**.*
2ff0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
3000: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
3010: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
3020: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
3030: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a  d statements],.*
3040: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
3050: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61  close | close] a
3060: 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ll [BLOB handles
3070: 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  ], and .** [sqli
3080: 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73  te3_backup_finis
3090: 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20  h | finish] all 
30a0: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
30b0: 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61   objects associa
30c0: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
30d0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
30e0: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
30f0: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
3100: 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a  e object.  ^If.*
3110: 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  * sqlite3_close_
3120: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  v2() is called o
3130: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
3140: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
3150: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
3160: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
3170: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
3180: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
3190: 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  nd/or.** [sqlite
31a0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31b0: 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  s then it return
31c0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e  s [SQLITE_OK] an
31d0: 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69  d the deallocati
31e0: 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63  on.** of resourc
31f0: 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75  es is deferred u
3200: 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72  ntil all [prepar
3210: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
3220: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a  [BLOB handles],.
3230: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
3240: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3250: 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79  are also destroy
3260: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3270: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3280: 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77  t is destroyed w
3290: 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69  hile a transacti
32a0: 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74  on is open,.** t
32b0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
32c0: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
32d0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
32e0: 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74  ** The C paramet
32f0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
3300: 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71  lose(C)] and [sq
3310: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43  lite3_close_v2(C
3320: 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
3330: 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  ther a NULL.** p
3340: 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71  ointer or an [sq
3350: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f  lite3] object po
3360: 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a  inter obtained.*
3370: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3380: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
3390: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a  3_open16()], or.
33a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
33b0: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
33c0: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
33d0: 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  d..** ^Calling s
33e0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f  qlite3_close() o
33f0: 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  r sqlite3_close_
3400: 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  v2() with a NULL
3410: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75   pointer.** argu
3420: 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65  ment is a harmle
3430: 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74  ss no-op..*/.int
3440: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73   sqlite3_close(s
3450: 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20 73 71  qlite3*);.int sq
3460: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73  lite3_close_v2(s
3470: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
3480: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20   The type for a 
3490: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
34a0: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65  n..** This is le
34b0: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61  gacy and depreca
34c0: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c  ted.  It is incl
34d0: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  uded for histori
34e0: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  cal.** compatibi
34f0: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  lity and is not 
3500: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74  documented..*/.t
3510: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c  ypedef int (*sql
3520: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76  ite3_callback)(v
3530: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
3540: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a   char**);../*.**
3550: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53   CAPI3REF: One-S
3560: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74  tep Query Execut
3570: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a  ion Interface.**
3580: 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
3590: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
35a0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
35b0: 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69  ace is a conveni
35c0: 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f  ence wrapper aro
35d0: 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
35e0: 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b  prepare_v3()], [
35f0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
3600: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
3610: 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68  nalize()],.** th
3620: 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70  at allows an app
3630: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20  lication to run 
3640: 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65  multiple stateme
3650: 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69  nts of SQL.** wi
3660: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20  thout having to 
3670: 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63  use a lot of C c
3680: 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode. .**.** ^The
3690: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
36a0: 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a  interface runs z
36b0: 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d  ero or more UTF-
36c0: 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65  8 encoded,.** se
36d0: 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
36e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
36f0: 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20  passed into its 
3700: 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a  2nd argument,.**
3710: 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20   in the context 
3720: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
3730: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73   connection] pas
3740: 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73  sed in as its 1s
3750: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  t.** argument.  
3760: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3770: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65   function of the
3780: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3790: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
37a0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  () is not NULL, 
37b0: 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b  then it is invok
37c0: 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75  ed for each resu
37d0: 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67  lt row.** coming
37e0: 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c   out of the eval
37f0: 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  uated SQL statem
3800: 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20  ents.  ^The 4th 
3810: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73  argument to.** s
3820: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3830: 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68   relayed through
3840: 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75   to the 1st argu
3850: 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20  ment of each.** 
3860: 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74  callback invocat
3870: 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ion.  ^If the ca
3880: 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74  llback pointer t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  .** is NULL, the
38b0: 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73  n no callback is
38c0: 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e   ever invoked an
38d0: 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72  d result rows ar
38e0: 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  e.** ignored..**
38f0: 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72  .** ^If an error
3900: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76   occurs while ev
3910: 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c  aluating the SQL
3920: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
3930: 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  ed into.** sqlit
3940: 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20  e3_exec(), then 
3950: 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
3960: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65   current stateme
3970: 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20  nt stops and.** 
3980: 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65  subsequent state
3990: 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65  ments are skippe
39a0: 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20  d.  ^If the 5th 
39b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
39c0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69  ite3_exec().** i
39d0: 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
39e0: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67  any error messag
39f0: 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  e is written int
3a00: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
3a10: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3a20: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
3a30: 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72   passed back thr
3a40: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72  ough the 5th par
3a50: 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76  ameter..** To av
3a60: 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73  oid memory leaks
3a70: 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
3a80: 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20  n should invoke 
3a90: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
3aa0: 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73  .** on error mes
3ab0: 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74  sage strings ret
3ac0: 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68  urned through th
3ad0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3ae0: 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  of.** sqlite3_ex
3af0: 65 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65  ec() after the e
3b00: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
3b10: 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ing is no longer
3b20: 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20   needed..** ^If 
3b30: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3b40: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3b50: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  c() is not NULL 
3b60: 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  and no errors.**
3b70: 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c   occur, then sql
3b80: 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73  ite3_exec() sets
3b90: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20   the pointer in 
3ba0: 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65  its 5th paramete
3bb0: 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66  r to.** NULL bef
3bc0: 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
3bd0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69  *.** ^If an sqli
3be0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3bf0: 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
3c00: 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65  zero, the sqlite
3c10: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74  3_exec().** rout
3c20: 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ine returns SQLI
3c30: 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74  TE_ABORT without
3c40: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61   invoking the ca
3c50: 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64  llback again and
3c60: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e  .** without runn
3c70: 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65  ing any subseque
3c80: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  nt SQL statement
3c90: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e  s..**.** ^The 2n
3ca0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3cb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3cc0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3cd0: 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  on is the.** num
3ce0: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
3cf0: 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e  n the result.  ^
3d00: 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  The 3rd argument
3d10: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
3d20: 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61  exec().** callba
3d30: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ck is an array o
3d40: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
3d50: 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61  rings obtained a
3d60: 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  s if from.** [sq
3d70: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
3d80: 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61  t()], one for ea
3d90: 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20  ch column.  ^If 
3da0: 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a  an element of a.
3db0: 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73  ** result row is
3dc0: 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
3dd0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72  orresponding str
3de0: 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ing pointer for 
3df0: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3e00: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3e10: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
3e20: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
3e30: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73  ment to the.** s
3e40: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3e50: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
3e60: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
3e70: 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20  o strings where 
3e80: 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65  each.** entry re
3e90: 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d  presents the nam
3ea0: 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69  e of correspondi
3eb0: 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ng result column
3ec0: 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20   as obtained.** 
3ed0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
3ee0: 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a  lumn_name()]..**
3ef0: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20  .** ^If the 2nd 
3f00: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3f10: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61  ite3_exec() is a
3f20: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61   NULL pointer, a
3f30: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61   pointer.** to a
3f40: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
3f50: 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61  or a pointer tha
3f60: 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20  t contains only 
3f70: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f  whitespace and/o
3f80: 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e  r .** SQL commen
3f90: 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20  ts, then no SQL 
3fa0: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
3fb0: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65  valuated and the
3fc0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
3fd0: 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  not changed..**.
3fe0: 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a  ** Restrictions:
3ff0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
4000: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4010: 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72 65 20  ion must ensure 
4020: 74 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72  that the 1st par
4030: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4040: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20  3_exec().**     
4050: 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20   is a valid and 
4060: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
4070: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c  onnection]..** <
4080: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4090: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ion must not clo
40a0: 73 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  se the [database
40b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
40c0: 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
40d0: 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65    the 1st parame
40e0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
40f0: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
4100: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
4110: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  nning..** <li> T
4120: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
4130: 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  ust not modify t
4140: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
4150: 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74   text passed int
4160: 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e  o.**      the 2n
4170: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
4180: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
4190: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
41a0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
41b0: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ul>.*/.int s
41c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
41d0: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
4200: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
4210: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
4220: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
4230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
4240: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
4250: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
4260: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
4270: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
4280: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
4290: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
42a0: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74            /* 1st
42d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
42e0: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
42f0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
4300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4310: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
4320: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
4330: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
4340: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
4350: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4360: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65   {result code de
4370: 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  finitions}.**.**
4380: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
4390: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
43a0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
43b0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
43c0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
43d0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
43e0: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
43f0: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
4400: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
4410: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
4420: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
4430: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4440: 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e  See also: [exten
4450: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4460: 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a  definitions].*/.
4470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4480: 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20  K           0   
4490: 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65  /* Successful re
44a0: 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e  sult */./* begin
44b0: 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f  ning-of-error-co
44c0: 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  des */.#define S
44d0: 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20  QLITE_ERROR     
44e0: 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72     1   /* SQL er
44f0: 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64  ror or missing d
4500: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4510: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e  ne SQLITE_INTERN
4520: 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e  AL     2   /* In
4530: 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72  ternal logic err
4540: 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a  or in SQLite */.
4550: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4560: 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20  ERM         3   
4570: 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73  /* Access permis
4580: 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  sion denied */.#
4590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
45a0: 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f  ORT        4   /
45b0: 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  * Callback routi
45c0: 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20  ne requested an 
45d0: 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65  abort */.#define
45e0: 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20   SQLITE_BUSY    
45f0: 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20       5   /* The 
4600: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
4610: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4620: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
4630: 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20         6   /* A 
4640: 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74  table in the dat
4650: 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20  abase is locked 
4660: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4670: 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37  E_NOMEM        7
4680: 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29     /* A malloc()
4690: 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69   failed */.#defi
46a0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
46b0: 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74  LY     8   /* At
46c0: 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61  tempt to write a
46d0: 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61   readonly databa
46e0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
46f0: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20  LITE_INTERRUPT  
4700: 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69    9   /* Operati
4710: 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79  on terminated by
4720: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
4730: 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pt()*/.#define S
4740: 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20  QLITE_IOERR     
4750: 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b    10   /* Some k
4760: 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20  ind of disk I/O 
4770: 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a  error occurred *
4780: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4790: 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20  _CORRUPT     11 
47a0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
47b0: 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20  e disk image is 
47c0: 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65  malformed */.#de
47d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46  fine SQLITE_NOTF
47e0: 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20  OUND    12   /* 
47f0: 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69  Unknown opcode i
4800: 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63  n sqlite3_file_c
4810: 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66  ontrol() */.#def
4820: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20  ine SQLITE_FULL 
4830: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49         13   /* I
4840: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20  nsertion failed 
4850: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65  because database
4860: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66   is full */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
4880: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55  PEN    14   /* U
4890: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68  nable to open th
48a0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
48b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
48c0: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35  E_PROTOCOL    15
48d0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c     /* Database l
48e0: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
48f0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4900: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
4910: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
4920: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
4930: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
4940: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4950: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
4960: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
4970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
4980: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
4990: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
49a0: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
49b0: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
49c0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
49d0: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
49e0: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
49f0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
4a00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4a10: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4a20: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4a30: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
4a40: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4a50: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
4a60: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
4a70: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
4a80: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
4a90: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4aa0: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4ab0: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4ac0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4ad0: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4ae0: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4af0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4b00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4b10: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4b20: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
4b30: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
4b40: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4b50: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
4b60: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
4b70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4b80: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
4b90: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
4ba0: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
4bb0: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
4bc0: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
4bd0: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
4be0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4bf0: 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20  ITE_NOTICE      
4c00: 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61  27   /* Notifica
4c10: 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74  tions from sqlit
4c20: 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66  e3_log() */.#def
4c30: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
4c40: 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57  NG     28   /* W
4c50: 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c  arnings from sql
4c60: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57  efine SQLITE_ROW
4c80: 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a           100  /*
4c90: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4ca0: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  has another row 
4cb0: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ready */.#define
4cc0: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20   SQLITE_DONE    
4cd0: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69      101  /* sqli
4ce0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66  te3_step() has f
4cf0: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
4d00: 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65  g */./* end-of-e
4d10: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f  rror-codes */../
4d20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
4d30: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
4d40: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
4d50: 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : {extended resu
4d60: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4d70: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74  ons}.**.** In it
4d80: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  s default config
4d90: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20  uration, SQLite 
4da0: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74  API routines ret
4db0: 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e  urn one of 30 in
4dc0: 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74  teger.** [result
4dd0: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4de0: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4df0: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
4e00: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
4e10: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
4e20: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
4e30: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
4e40: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
4e50: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4e60: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4e70: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4e80: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4e90: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4ea0: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4eb0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4ec0: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4ed0: 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33 2e 38  .8 [dateof:3.3.8
4ee0: 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72 29 20  ].** and later) 
4ef0: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4f00: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4f10: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4f20: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4f30: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4f40: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4f50: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
4f60: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f70: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
4f80: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4f90: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4fa0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4fb0: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4fc0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4fd0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4fe0: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
4ff0: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
5000: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
5010: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
5020: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
5030: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
5040: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
5050: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5060: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5070: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5080: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5090: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50a0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
50b0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
50c0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
50d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50e0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
50f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5100: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5110: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5120: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5130: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5140: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5180: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
51a0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
51b0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
51c0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
51d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51e0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
51f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5200: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5220: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5230: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5240: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5250: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5260: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5270: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5280: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5290: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52a0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
52b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52c0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
52d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52e0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
52f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5300: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5310: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5320: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5330: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5340: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5350: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5360: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5370: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5380: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5390: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53a0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
53b0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
53c0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
53d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53e0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
53f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5400: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5410: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5420: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5430: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5440: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5450: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5460: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5470: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5480: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5490: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54a0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
54b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54c0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
54d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54e0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
54f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5500: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5510: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5520: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5530: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5540: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5550: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5560: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5570: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5580: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5590: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55a0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
55b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55c0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
55d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55e0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
55f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5600: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5620: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5630: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5640: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5650: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5660: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5670: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5680: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5690: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56a0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
56b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56c0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
56d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56e0: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
56f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5700: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
5710: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5720: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
5730: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5740: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
5750: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5760: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5770: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5780: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
57a0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
57b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
57c0: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
57d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
57e0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
57f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5800: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5820: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5830: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5840: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5860: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5870: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5880: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5890: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
58a0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
58b0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
58c0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
58d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
58e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
58f0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5900: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5910: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5920: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5930: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
5940: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
5950: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5960: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5970: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5980: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5990: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
59a0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
59b0: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
59c0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
59d0: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
59e0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
59f0: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5a00: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5a10: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5a30: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5a50: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
5a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
5a70: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
5a80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
5a90: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5aa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5ab0: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5ac0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5ad0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5af0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5b00: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5b10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b40: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
5b50: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b60: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5b70: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5b80: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
5b90: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5ba0: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5bc0: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5bd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5be0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5bf0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5c00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5c10: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5c20: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5c30: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5c40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c50: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
5c60: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c70: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
5c80: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5c90: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5ca0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5cb0: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5cd0: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5ce0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5cf0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5d00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5d20: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5d30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5d40: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5d50: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5d60: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5d70: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5d80: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5d90: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5da0: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5db0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5dc0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5dd0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5de0: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5df0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5e00: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5e10: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
5e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
5e30: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
5e40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5e50: 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52  LITE_OK_LOAD_PER
5e60: 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53 51  MANENTLY     (SQ
5e70: 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29  LITE_OK | (1<<8)
5e80: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5e90: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5ea0: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5eb0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5ec0: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5ed0: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5ee0: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5ef0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5f00: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5f10: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
5f20: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
5f30: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5f40: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
5f50: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
5f60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f70: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5f80: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5f90: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5fa0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5fb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5fc0: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5fd0: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5fe0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5ff0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6010: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
6020: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
6030: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6040: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6060: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
6070: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
6080: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60a0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
60b0: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
60c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
60d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60e0: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
60f0: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
6100: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6120: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
6130: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
6140: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6150: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6170: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
6180: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
6190: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
61a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
61b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61c0: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
61d0: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
61e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6200: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
6210: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
6220: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6240: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
6250: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
6260: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6280: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
6290: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
62a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62c0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
62d0: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
62e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6300: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
6310: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
6320: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6340: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
6350: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
6360: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6380: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
6390: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
63a0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
63b0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
63c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
63d0: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
63e0: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
63f0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6400: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6420: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
6430: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
6440: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6450: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6470: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
6480: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
6490: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
64a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
64b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
64c0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
64d0: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
64e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
64f0: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
6500: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6510: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
6520: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6530: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
6540: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
6550: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
6560: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
6570: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
6580: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
6590: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
65a0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
65b0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
65c0: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
65d0: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
65e0: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
65f0: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
6600: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
6610: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
6620: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
6630: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6640: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
6650: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
6660: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
6670: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6680: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
6690: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
66a0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
66b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
66c0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
66d0: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
66e0: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
66f0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
6700: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
6710: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
6720: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
6730: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
6740: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
6750: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
6760: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
6770: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
6780: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
6790: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
67a0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
67b0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
67c0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
67d0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
67e0: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
67f0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
6800: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
6810: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6820: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
6830: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6840: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
6850: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
6860: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
6870: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
6880: 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68  to xWrite().  Th
6890: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
68a0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
68b0: 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  TE property mean
68c0: 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20  s that.** after 
68d0: 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67  reboot following
68e0: 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65   a crash or powe
68f0: 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79  r loss, the only
6900: 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66   bytes in a.** f
6910: 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72  ile that were wr
6920: 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70  itten at the app
6930: 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d  lication level m
6940: 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65  ight have change
6950: 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64  d.** and that ad
6960: 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76  jacent bytes, ev
6970: 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20  en bytes within 
6980: 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20  the same sector 
6990: 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  are.** guarantee
69a0: 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65  d to be unchange
69b0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
69c0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
69d0: 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c  _WHEN_OPEN.** fl
69e0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
69f0: 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  t a file cannot 
6a00: 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  be deleted when 
6a10: 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51  open.  The.** SQ
6a20: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6a30: 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61  ABLE flag indica
6a40: 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c  tes that the fil
6a50: 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d  e is on.** read-
6a60: 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63  only media and c
6a70: 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
6a80: 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73   even by process
6a90: 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61  es with.** eleva
6aa0: 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a  ted privileges..
6ab0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
6ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6ae0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
6af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6b00: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
6b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
6b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
6b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6b50: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
6b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6b70: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
6b80: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
6b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6ba0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
6bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6bc0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
6bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6be0: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
6bf0: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
6c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6c10: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
6c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6c30: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
6c40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
6c50: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
6c60: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
6c70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6c80: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
6c90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6ca0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6cb0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
6cc0: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
6cd0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
6ce0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
6cf0: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
6d00: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
6d10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6d20: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
6d30: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
6d40: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
6d50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
6d60: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
6d70: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
6d80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6d90: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20  AP_IMMUTABLE    
6da0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6db0: 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  2000../*.** CAPI
6dc0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
6dd0: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
6de0: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
6df0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
6e00: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6e10: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
6e20: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
6e30: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
6e40: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
6e50: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
6e60: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
6e70: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
6e80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6e90: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
6ea0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
6eb0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
6ec0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
6ed0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
6ee0: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
6ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6f00: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
6f10: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
6f20: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
6f30: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
6f40: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
6f50: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
6f60: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  s.**.** When SQL
6f70: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
6f80: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
6f90: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
6fa0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6fb0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
6fc0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
6fd0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6fe0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6ff0: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
7000: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
7010: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7020: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
7030: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
7040: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
7050: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
7060: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
7070: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
7080: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
7090: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
70a0: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c  lushed. If the l
70b0: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f  ower four bits o
70c0: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71  f the flag.** eq
70d0: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
70e0: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61  NORMAL, that mea
70f0: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c  ns to use normal
7100: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69   fsync() semanti
7110: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f  cs..** If the lo
7120: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71  wer four bits eq
7130: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
7140: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  FULL, that means
7150: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
7160: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
7170: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
7180: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20  ync()..**.** Do 
7190: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20  not confuse the 
71a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
71b0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
71c0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a  NC_FULL flags.**
71d0: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d   with the [PRAGM
71e0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e  A synchronous]=N
71f0: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d  ORMAL and [PRAGM
7200: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46  A synchronous]=F
7210: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e  ULL.** settings.
7220: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f    The [synchrono
7230: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72  us pragma] deter
7240: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73  mines when calls
7250: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63   to the.** xSync
7260: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75   VFS method occu
7270: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e  r and applies un
7280: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61  iformly across a
7290: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a  ll platforms..**
72a0: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
72b0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
72c0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
72d0: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77  gs determine how
72e0: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72  .** energetic or
72f0: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72   rigorous or for
7300: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f  ceful the sync o
7310: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e  perations are an
7320: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61  d.** only make a
7330: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d   difference on M
7340: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64  ac OSX for the d
7350: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f  efault SQLite co
7360: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61  de..** (Third-pa
7370: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  rty VFS implemen
7380: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c  tations might al
7390: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  so make the dist
73a0: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
73b0: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  en SQLITE_SYNC_N
73c0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
73d0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20  _SYNC_FULL, but 
73e0: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65  among the.** ope
73f0: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e  rating systems n
7400: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65  atively supporte
7410: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c  d by SQLite, onl
7420: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72  y Mac OSX.** car
7430: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66  es about the dif
7440: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65  ference.).*/.#de
7450: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7460: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
7470: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
7480: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
7490: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
74a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
74b0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
74c0: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
74d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
74e0: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
74f0: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
7500: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
7510: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
7520: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
7530: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
7540: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
7550: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
7560: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
7570: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
7580: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
7590: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
75a0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
75b0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
75c0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
75d0: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
75e0: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
75f0: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
7600: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
7610: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7620: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
7630: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
7640: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
7650: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
7660: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
7670: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
7680: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
7690: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
76a0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
76b0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
76c0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
76d0: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
76e0: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
76f0: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
7700: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
7710: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
7720: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
7730: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
7740: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
7750: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
7760: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7770: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  en] method popul
7780: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
7790: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
77a0: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
77b0: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
77c0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
77d0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
77e0: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
77f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
7800: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
7810: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
7820: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
7830: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
7840: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
7850: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
7860: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
7870: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
7880: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7890: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
78a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
78b0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
78c0: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33  sets the sqlite3
78d0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
78e0: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20  lement .** to a 
78f0: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
7900: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
7910: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43  e3_io_methods.xC
7920: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d  lose method.** m
7930: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76  ay be invoked ev
7940: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  en if the [sqlit
7950: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65  e3_vfs.xOpen] re
7960: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
7970: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
7980: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
7990: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
79a0: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
79b0: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f  failed [sqlite3_
79c0: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73  vfs.xOpen].** is
79d0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
79e0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20  3_vfs.xOpen] to 
79f0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
7a00: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7a10: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  ement.** to NULL
7a20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
7a30: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
7a40: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
7a50: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
7a60: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
7a70: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
7a80: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
7a90: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
7aa0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
7ab0: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
7ac0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
7ad0: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
7ae0: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
7af0: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
7b00: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
7b10: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
7b20: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
7b30: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
7b40: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
7b50: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
7b60: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
7b70: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
7b80: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
7b90: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
7ba0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
7bb0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
7bc0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
7bd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7be0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7bf0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7c00: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7c10: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
7c20: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
7c30: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7c40: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
7c50: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
7c60: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
7c70: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
7c80: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
7c90: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
7ca0: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
7cb0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
7cc0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
7cd0: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
7ce0: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
7cf0: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
7d00: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
7d10: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
7d20: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
7d30: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
7d40: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
7d50: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
7d60: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
7d70: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
7d80: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
7d90: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
7da0: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
7db0: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
7dc0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
7dd0: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
7de0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
7df0: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
7e00: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
7e10: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
7e20: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
7e30: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
7e40: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
7e50: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
7e60: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
7e70: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
7e80: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
7e90: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
7ea0: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
7eb0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
7ec0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
7ed0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
7ee0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
7ef0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
7f00: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
7f10: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
7f20: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
7f30: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
7f40: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
7f50: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
7f60: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
7f70: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
7f80: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
7f90: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
7fa0: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
7fb0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
7fc0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
7fd0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
7fe0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
7ff0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
8000: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
8010: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
8020: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
8030: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
8040: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
8050: 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f  odes | list of o
8060: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
8070: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
8080: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
8090: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
80a0: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
80b0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
80c0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
80d0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
80e0: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
80f0: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70  flicts.  VFS imp
8100: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
8110: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
8120: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20  QLITE_NOTFOUND] 
8130: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  for file control
8140: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68   opcodes that th
8150: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63  ey do not.** rec
8160: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  ognize..**.** Th
8170: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
8180: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
8190: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
81a0: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
81b0: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
81c0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
81d0: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
81e0: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
81f0: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
8200: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
8210: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
8220: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
8230: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
8240: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8250: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
8260: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
8270: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
8280: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
8290: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
82a0: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
82b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
82c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
82d0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
82e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
82f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8300: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
8310: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8320: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
8330: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8340: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
8350: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8360: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
8370: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8380: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
8390: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
83a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
83b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
83c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
83d0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
83e0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
83f0: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
8400: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8410: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENTIAL].** <li> 
8420: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e  [SQLITE_IOCAP_UN
8430: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
8440: 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  PEN].** <li> [SQ
8450: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
8460: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 0a  SAFE_OVERWRITE].
8470: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8480: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d  IOCAP_IMMUTABLE]
8490: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
84a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
84b0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
84c0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
84d0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
84e0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
84f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8500: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8510: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8520: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8530: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
8540: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8550: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8560: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8570: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8580: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
8590: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
85a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
85b0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
85c0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
85d0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
85e0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
85f0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8600: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8610: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8620: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8630: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
8640: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8650: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8660: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8670: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8680: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
8690: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
86a0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
86b0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
86c0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
86d0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
86e0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
86f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8700: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
8710: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
8720: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
8730: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
8740: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
8750: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
8760: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
8770: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
8780: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
8790: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
87a0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
87b0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
87c0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
87d0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
87e0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
87f0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8800: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8810: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
8820: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
8830: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8840: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
8850: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
8860: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8870: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
8880: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8890: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
88a0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
88b0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
88c0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
88d0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
88e0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
88f0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8900: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
8910: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
8920: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8930: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
8940: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
8950: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
8960: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
8970: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
8980: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8990: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
89a0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
89b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
89c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
89d0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
89e0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
89f0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8a00: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8a10: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
8a20: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
8a30: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
8a40: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
8a50: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
8a60: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
8a70: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8a80: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
8a90: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
8aa0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8ab0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8ac0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8ad0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
8ae0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8af0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8b00: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
8b10: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
8b20: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
8b30: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
8b40: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
8b50: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
8b60: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
8b70: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
8b80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8b90: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
8ba0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8bb0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
8bc0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8bd0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8be0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8bf0: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8c00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8c10: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8c20: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8c30: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8c40: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8c50: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8c60: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8c70: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8c80: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8c90: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8ca0: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8cb0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8cc0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8cd0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8ce0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8cf0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8d00: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8d10: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
8d20: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
8d30: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
8d40: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
8d50: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8d60: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
8d70: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
8d80: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8d90: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
8da0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8db0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
8dc0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
8dd0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
8de0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
8df0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8e00: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
8e10: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
8e20: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8e30: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8e40: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8e50: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8e60: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8e70: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8e80: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8e90: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8ea0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8eb0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8ec0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8ed0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8ee0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8ef0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8f00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8f10: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8f20: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8f30: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8f40: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8f50: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8f60: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8f70: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8f80: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8f90: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
8fa0: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
8fb0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
8fc0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8fd0: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
8fe0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8ff0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
9000: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9010: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
9020: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9030: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
9040: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
9050: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
9060: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
9070: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
9080: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
9090: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
90a0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
90b0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
90c0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
90d0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
90e0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
90f0: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
9100: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
9110: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
9120: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
9130: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
9140: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
9150: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
9160: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
9170: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
9180: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
9190: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
91a0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
91b0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
91c0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
91d0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
91e0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
91f0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
9200: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
9210: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9220: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
9230: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
9240: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
9250: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
9260: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
9270: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
9280: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
9290: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
92a0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
92b0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
92c0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
92d0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
92e0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
92f0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
9300: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
9310: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
9320: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
9330: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
9340: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
9350: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
9360: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
9370: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9380: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
9390: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
93a0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
93b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
93c0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
93d0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
93e0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
93f0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9400: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9410: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9420: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
9430: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9440: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
9450: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
9460: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
9470: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9480: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
9490: 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  AL_POINTER]].** 
94a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
94b0: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
94c0: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
94d0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
94e0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
94f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9500: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9510: 20 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61   with the journa
9520: 6c 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a  l file (either.*
9530: 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20  * the [rollback 
9540: 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20  journal] or the 
9550: 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67  [write-ahead log
9560: 5d 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ]) for a particu
9570: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
9580: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
9590: 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43   also [SQLITE_FC
95a0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
95b0: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
95c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
95d0: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f  _OMITTED]].** No
95e0: 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a   longer in use..
95f0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9600: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a  TE_FCNTL_SYNC]].
9610: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9620: 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64  CNTL_SYNC] opcod
9630: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
9640: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
9650: 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20  ite and.** sent 
9660: 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64  to the VFS immed
9670: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68  iately before th
9680: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
9690: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a  s invoked on a.*
96a0: 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  * database file 
96b0: 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20  descriptor. Or, 
96c0: 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  if the xSync met
96d0: 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  hod is not invok
96e0: 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74  ed .** because t
96f0: 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66  he user has conf
9700: 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69  igured SQLite wi
9710: 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73  th .** [PRAGMA s
9720: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
9730: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
9740: 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b  OFF] it is invok
9750: 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20  ed in place .** 
9760: 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  of the xSync met
9770: 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73  hod. In most cas
9780: 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20  es, the pointer 
9790: 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
97a0: 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c  with.** this fil
97b0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c  e-control is NUL
97c0: 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74  L. However, if t
97d0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
97e0: 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64   is being synced
97f0: 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61  .** as part of a
9800: 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20   multi-database 
9810: 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75  commit, the argu
9820: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
9830: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
9840: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
9850: 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63  ning the transac
9860: 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75  tions master-jou
9870: 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20  rnal file name. 
9880: 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64  VFSes that .** d
9890: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
98a0: 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69  signal should si
98b0: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
98c0: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
98d0: 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75  cations .** shou
98e0: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
98f0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9900: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
9910: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
9920: 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70  o may .** disrup
9930: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  t the operation 
9940: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
9950: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
9960: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
9970: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9980: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
9990: 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65  HASETWO]].** The
99a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
99b0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20  OMMIT_PHASETWO] 
99c0: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
99d0: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
99e0: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
99f0: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9a00: 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74  after a transact
9a10: 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  ion has been com
9a20: 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65  mitted immediate
9a30: 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65  ly.** but before
9a40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
9a50: 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73   unlocked. VFSes
9a60: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65   that do not nee
9a70: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a  d this signal.**
9a80: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
9a90: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
9aa0: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
9ab0: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
9ac0: 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  l.** [sqlite3_fi
9ad0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
9ae0: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
9af0: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
9b00: 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f  isrupt the .** o
9b10: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9b20: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
9b30: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
9b40: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
9b50: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9b60: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9b70: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9b80: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
9b90: 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69  _RETRY] opcode i
9ba0: 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
9bb0: 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a  ure automatic.**
9bc0: 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e   retry counts an
9bd0: 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20  d intervals for 
9be0: 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f  certain disk I/O
9bf0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20   operations for 
9c00: 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b  the.** windows [
9c10: 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
9c20: 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e   provide robustn
9c30: 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65  ess in the prese
9c40: 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76  nce of.** anti-v
9c50: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20  irus programs.  
9c60: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
9c70: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c  windows VFS will
9c80: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64   retry file read
9c90: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c  ,.** file write,
9ca0: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65   and file delete
9cb0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74   operations up t
9cc0: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68  o 10 times, with
9cd0: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32   a delay.** of 2
9ce0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  5 milliseconds b
9cf0: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20  efore the first 
9d00: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74  retry and with t
9d10: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73  he delay increas
9d20: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64  ing.** by an add
9d30: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69  itional 25 milli
9d40: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63  seconds with eac
9d50: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74  h subsequent ret
9d60: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ry.  This.** opc
9d70: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65  ode allows these
9d80: 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20   two values (10 
9d90: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d  retries and 25 m
9da0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64  illiseconds of d
9db0: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61  elay).** to be a
9dc0: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61  djusted.  The va
9dd0: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64  lues are changed
9de0: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73   for all databas
9df0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
9e00: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
9e10: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61   process.  The a
9e20: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
9e30: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79  nter to an array
9e40: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67   of two.** integ
9e50: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69  ers where the fi
9e60: 72 73 74 20 69 6e 74 65 67 65 72 20 69 73 20 74  rst integer is t
9e70: 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75  he new retry cou
9e80: 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nt and the secon
9e90: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20  d.** integer is 
9ea0: 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65  the delay.  If e
9eb0: 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73  ither integer is
9ec0: 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
9ed0: 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69  the setting.** i
9ee0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75  s not changed bu
9ef0: 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72  t instead the pr
9f00: 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61  ior value of tha
9f10: 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69  t setting is wri
9f20: 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  tten.** into the
9f30: 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c   array entry, al
9f40: 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65  lowing the curre
9f50: 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67  nt retry setting
9f60: 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72  s to be.** inter
9f70: 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44  rogated.  The zD
9f80: 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  bName parameter 
9f90: 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
9fa0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9fb0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9fc0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9fd0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9fe0: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20  _WAL] opcode is 
9ff0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
a000: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
a010: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72  istent [WAL | Wr
a020: 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73  ite Ahead Log] s
a030: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61  etting.  By defa
a040: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61  ult, the auxilia
a050: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61  ry.** write ahea
a060: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64  d log and shared
a070: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73   memory files us
a080: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69  ed for transacti
a090: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72  on control.** ar
a0a0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
a0b0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
a0c0: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69   latest connecti
a0d0: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  on to the databa
a0e0: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53  se.** closes.  S
a0f0: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e  etting persisten
a100: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65  t WAL mode cause
a110: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f  s those files to
a120: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a   persist after.*
a130: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73  * close.  Persis
a140: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69  ting the files i
a150: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74  s useful when ot
a160: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68  her processes th
a170: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76  at do not.** hav
a180: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69  e write permissi
a190: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74  on on the direct
a1a0: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ory containing t
a1b0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
a1c0: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64   want.** to read
a1d0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
a1e0: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61  le, as the WAL a
a1f0: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
a200: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73   files must exis
a210: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f  t.** in order fo
a220: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  r the database t
a230: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20  o be readable.  
a240: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
a250: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
a260: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a270: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
a280: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
a290: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
a2a0: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
a2b0: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
a2c0: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  isable persisten
a2d0: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20  t WAL mode or 1 
a2e0: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73  to enable persis
a2f0: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65  tent.** WAL mode
a300: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
a310: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
a320: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
a330: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
a340: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65  .** WAL persiste
a350: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  nce setting..**.
a360: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a370: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
a380: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
a390: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a3a0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
a3b0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a3c0: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
a3d0: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
a3e0: 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61  sistent "powersa
a3f0: 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72  fe-overwrite" or
a400: 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e   "PSOW" setting.
a410: 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69    The PSOW setti
a420: 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73  ng.** determines
a430: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43   the [SQLITE_IOC
a440: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
a450: 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74  RWRITE] bit of t
a460: 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61  he.** xDeviceCha
a470: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
a480: 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68  hods. The fourth
a490: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
a4a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
a4b0: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
a4c0: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
a4d0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
a4e0: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
a4f0: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
a500: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72  0 to disable zer
a510: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72  o-damage mode or
a520: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72   1 to enable zer
a530: 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65  o-damage.** mode
a540: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
a550: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
a560: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
a570: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
a580: 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  .** zero-damage 
a590: 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  mode setting..**
a5a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a5b0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
a5c0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a5d0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
a5e0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e  TE] opcode is in
a5f0: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
a600: 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a  after opening.**
a610: 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63   a write transac
a620: 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  tion to indicate
a630: 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74   that, unless it
a640: 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   is rolled back 
a650: 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73  for some.** reas
a660: 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64  on, the entire d
a670: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
a680: 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  l be overwritten
a690: 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20   by the current 
a6a0: 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  .** transaction.
a6b0: 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79   This is used by
a6c0: 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f   VACUUM operatio
a6d0: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ns..**.** <li>[[
a6e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
a6f0: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  NAME]].** ^The [
a700: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
a710: 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e  NAME] opcode can
a720: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
a730: 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a  in the names of.
a740: 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69  ** all [VFSes] i
a750: 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e  n the VFS stack.
a760: 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20    The names are 
a770: 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73  of all VFS shims
a780: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61   and the.** fina
a790: 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56  l bottom-level V
a7a0: 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69  FS are written i
a7b0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
a7c0: 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
a7d0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
a7e0: 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69  and the result i
a7f0: 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20  s stored in the 
a800: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a  char* variable.*
a810: 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74  * that the fourt
a820: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b  h parameter of [
a830: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a840: 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74  trol()] points t
a850: 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72  o..** The caller
a860: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
a870: 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20  for freeing the 
a880: 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65  memory when done
a890: 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c  .  As with.** al
a8a0: 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61  l file-control a
a8b0: 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73  ctions, there is
a8c0: 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68   no guarantee th
a8d0: 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74  at this will act
a8e0: 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74  ually.** do anyt
a8f0: 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73  hing.  Callers s
a900: 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65  hould initialize
a910: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
a920: 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a  ble to a NULL.**
a930: 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65   pointer in case
a940: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
a950: 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d  ol is not implem
a960: 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c  ented.  This fil
a970: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20  e-control.** is 
a980: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61  intended for dia
a990: 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79  gnostic use only
a9a0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a9b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
a9c0: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65  OINTER]].** ^The
a9d0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
a9e0: 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  FS_POINTER] opco
a9f0: 64 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74  de finds a point
aa00: 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65  er to the top-le
aa10: 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63  vel.** [VFSes] c
aa20: 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e  urrently in use.
aa30: 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74    ^(The argument
aa40: 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   X in.** sqlite3
aa50: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62  _file_control(db
aa60: 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  ,SQLITE_FCNTL_VF
aa70: 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73  S_POINTER,X) mus
aa80: 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20  t be.** of type 
aa90: 22 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a  "[sqlite3_vfs] *
aaa0: 2a 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65  *".  This opcode
aab0: 73 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a  s will set *X.**
aac0: 20 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   to a pointer to
aad0: 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56   the top-level V
aae0: 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74  FS.)^.** ^When t
aaf0: 68 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c  here are multipl
ab00: 65 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74  e VFS shims in t
ab10: 68 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f  he stack, this o
ab20: 70 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a  pcode finds the.
ab30: 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68  ** upper-most sh
ab40: 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c  im only..**.** <
ab50: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ab60: 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57  L_PRAGMA]].** ^W
ab70: 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d  henever a [PRAGM
ab80: 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  A] statement is 
ab90: 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49  parsed, an [SQLI
aba0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
abb0: 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f   .** file contro
abc0: 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65  l is sent to the
abd0: 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   open [sqlite3_f
abe0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72  ile] object corr
abf0: 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20  esponding.** to 
ac00: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
ac10: 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70  e to which the p
ac20: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
ac30: 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67  refers. ^The arg
ac40: 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
ac50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ac60: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ac70: 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ol is an array o
ac80: 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  f.** pointers to
ac90: 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a   strings (char**
aca0: 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73  ) in which the s
acb0: 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66  econd element of
acc0: 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73   the array.** is
acd0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
ace0: 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20   pragma and the 
acf0: 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73  third element is
ad00: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
ad10: 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f   the.** pragma o
ad20: 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72  r NULL if the pr
ad30: 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75  agma has no argu
ad40: 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64  ment.  ^The hand
ad50: 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53  ler for an.** [S
ad60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ad70: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
ad80: 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   can optionally 
ad90: 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65  make the first e
ada0: 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65  lement.** of the
adb0: 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74   char** argument
adc0: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
add0: 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
ade0: 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
adf0: 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65  f()].** or the e
ae00: 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68  quivalent and th
ae10: 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  at string will b
ae20: 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74  ecome the result
ae30: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f   of the pragma o
ae40: 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d  r.** the error m
ae50: 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72  essage if the pr
ae60: 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20  agma fails. ^If 
ae70: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
ae80: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
ae90: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
aea0: 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  s [SQLITE_NOTFOU
aeb0: 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c  ND], then normal
aec0: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72   .** [PRAGMA] pr
aed0: 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75  ocessing continu
aee0: 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51  es.  ^If the [SQ
aef0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
af00: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
af10: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
af20: 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65  TE_OK], then the
af30: 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20   parser assumes 
af40: 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20  that the.** VFS 
af50: 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20  has handled the 
af60: 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e  PRAGMA itself an
af70: 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e  d the parser gen
af80: 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a  erates a no-op.*
af90: 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
afa0: 6d 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73  ment if result s
afb0: 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f  tring is NULL, o
afc0: 72 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61  r that returns a
afd0: 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
afe0: 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66  result string if
aff0: 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e   the string is n
b000: 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20  on-NULL..** ^If 
b010: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
b020: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
b030: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a  ontrol returns.*
b040: 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64  * any result cod
b050: 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
b060: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c  LITE_OK] or [SQL
b070: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
b080: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  hat means.** tha
b090: 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e  t the VFS encoun
b0a0: 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77  tered an error w
b0b0: 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68  hile handling th
b0c0: 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74  e [PRAGMA] and t
b0d0: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f  he.** compilatio
b0e0: 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20  n of the PRAGMA 
b0f0: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72  fails with an er
b100: 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  ror.  ^The [SQLI
b110: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b120: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
b130: 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62   occurs at the b
b140: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67  eginning of prag
b150: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61  ma statement ana
b160: 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20  lysis and so.** 
b170: 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76  it is able to ov
b180: 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20  erride built-in 
b190: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
b1a0: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nts..**.** <li>[
b1b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
b1c0: 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e  SYHANDLER]].** ^
b1d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b1e0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a  L_BUSYHANDLER].*
b1f0: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d  * file-control m
b200: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79  ay be invoked by
b210: 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64   SQLite on the d
b220: 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e  atabase file han
b230: 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61  dle.** shortly a
b240: 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65  fter it is opene
b250: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  d in order to pr
b260: 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56  ovide a custom V
b270: 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a  FS with access.*
b280: 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74  * to the connect
b290: 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65  ions busy-handle
b2a0: 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20  r callback. The 
b2b0: 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74  argument is of t
b2c0: 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a  ype (void **).**
b2d0: 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74   - an array of t
b2e0: 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75  wo (void *) valu
b2f0: 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76  es. The first (v
b300: 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20  oid *) actually 
b310: 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66  points.** to a f
b320: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
b330: 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29  (int (*)(void *)
b340: 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69  ). In order to i
b350: 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63  nvoke the connec
b360: 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61  tions.** busy-ha
b370: 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63  ndler, this func
b380: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69  tion should be i
b390: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20  nvoked with the 
b3a0: 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20  second (void *) 
b3b0: 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20  in.** the array 
b3c0: 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75  as the only argu
b3d0: 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75  ment. If it retu
b3e0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
b3f0: 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  en the operation
b400: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
b410: 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74  tried. If it ret
b420: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63  urns zero, the c
b430: 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64  ustom VFS should
b440: 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20   abandon the.** 
b450: 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
b460: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
b470: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
b480: 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41  FILENAME]].** ^A
b490: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69  pplication can i
b4a0: 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54  nvoke the [SQLIT
b4b0: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
b4c0: 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72  NAME] file-contr
b4d0: 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51  ol.** to have SQ
b4e0: 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a  Lite generate a.
b4f0: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
b500: 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20  ename using the 
b510: 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74  same algorithm t
b520: 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20  hat is followed 
b530: 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74  to generate.** t
b540: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
b550: 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c  es for TEMP tabl
b560: 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74  es and other int
b570: 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65  ernal uses.  The
b580: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
b590: 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20  uld be a char** 
b5a0: 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69  which will be fi
b5b0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69  lled with the fi
b5c0: 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65  lename.** writte
b5d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
b5e0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
b5f0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
b600: 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75   The caller shou
b610: 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71  ld.** invoke [sq
b620: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
b630: 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61   the result to a
b640: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65  void a memory le
b650: 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ak..**.** <li>[[
b660: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
b670: 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  P_SIZE]].** The 
b680: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
b690: 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
b6a0: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f  ntrol is used to
b6b0: 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68   query or set th
b6c0: 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  e.** maximum num
b6d0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61  ber of bytes tha
b6e0: 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66  t will be used f
b6f0: 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64  or memory-mapped
b700: 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67   I/O..** The arg
b710: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
b720: 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66  er to a value of
b730: 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e   type sqlite3_in
b740: 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61  t64 that.** is a
b750: 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d  n advisory maxim
b760: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
b770: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74  es in the file t
b780: 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54  o memory map.  T
b790: 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73  he.** pointer is
b7a0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
b7b0: 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e  h the old value.
b7c0: 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e    The limit is n
b7d0: 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a  ot changed if.**
b7e0: 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69   the value origi
b7f0: 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f  nally pointed to
b800: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e   is negative, an
b810: 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74  d so the current
b820: 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62   limit .** can b
b830: 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73  e queried by pas
b840: 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65  sing in a pointe
b850: 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20  r to a negative 
b860: 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a  number.  This.**
b870: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
b880: 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
b890: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50   to implement [P
b8a0: 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
b8b0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b8c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
b8d0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b8e0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66  E_FCNTL_TRACE] f
b8f0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76  ile control prov
b900: 69 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e  ides advisory in
b910: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20  formation.** to 
b920: 74 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68  the VFS about wh
b930: 61 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61  at the higher la
b940: 79 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69  yers of the SQLi
b950: 74 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69  te stack are doi
b960: 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65  ng..** This file
b970: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b980: 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74   by some VFS act
b990: 69 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73  ivity tracing [s
b9a0: 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72  hims]..** The ar
b9b0: 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f  gument is a zero
b9c0: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
b9d0: 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65  ng.  Higher laye
b9e0: 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c  rs in the.** SQL
b9f0: 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65  ite stack may ge
ba00: 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73  nerate instances
ba10: 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f   of this file co
ba20: 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20  ntrol if.** the 
ba30: 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54  [SQLITE_USE_FCNT
ba40: 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65  L_TRACE] compile
ba50: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
ba60: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  enabled..**.** <
ba70: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ba80: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a  L_HAS_MOVED]].**
ba90: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
baa0: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69  TL_HAS_MOVED] fi
bab0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72  le control inter
bac0: 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65  prets its argume
bad0: 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  nt as a.** point
bae0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
baf0: 20 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61   and it writes a
bb00: 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68   boolean into th
bb10: 61 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e  at integer depen
bb20: 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  ding.** on wheth
bb30: 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69  er or not the fi
bb40: 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61  le has been rena
bb50: 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64  med, moved, or d
bb60: 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a  eleted since it.
bb70: 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65  ** was first ope
bb80: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ned..**.** <li>[
bb90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
bba0: 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d  N32_GET_HANDLE]]
bbb0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bbc0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
bbd0: 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63  HANDLE] opcode c
bbe0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
bbf0: 74 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65  tain the.** unde
bc00: 72 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69  rlying native fi
bc10: 6c 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69  le handle associ
bc20: 61 74 65 64 20 77 69 74 68 20 61 20 66 69 6c 65  ated with a file
bc30: 20 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66   handle.  This f
bc40: 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69  ile.** control i
bc50: 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72  nterprets its ar
bc60: 67 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e  gument as a poin
bc70: 74 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20  ter to a native 
bc80: 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a  file handle and.
bc90: 2a 2a 20 77 72 69 74 65 73 20 74 68 65 20 72 65  ** writes the re
bca0: 73 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68  sulting value th
bcb0: 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ere..**.** <li>[
bcc0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
bcd0: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d  N32_SET_HANDLE]]
bce0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bcf0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
bd00: 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69  HANDLE] opcode i
bd10: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
bd20: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
bd30: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
bd40: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
bd50: 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65  thod to swap the
bd60: 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74   file handle wit
bd70: 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69  h the one.** poi
bd80: 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70  nted to by the p
bd90: 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54  Arg argument.  T
bda0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69  his capability i
bdb0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
bdc0: 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  sting.** and onl
bdd0: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
bde0: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
bdf0: 49 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69  ITE_TEST is defi
be00: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ned..**.** <li>[
be10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
be20: 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65  L_BLOCK]].** The
be30: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
be40: 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73  AL_BLOCK] is a s
be50: 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53  ignal to the VFS
be60: 20 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d   layer that it m
be70: 69 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e  ight.** be advan
be80: 74 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b  tageous to block
be90: 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c   on the next WAL
bea0: 20 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63   lock if the loc
beb0: 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61  k is not immedia
bec0: 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c  tely.** availabl
bed0: 65 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73  e.  The WAL subs
bee0: 79 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69  ystem issues thi
bef0: 73 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20  s signal during 
bf00: 72 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74  rare.** circumst
bf10: 61 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74  ances in order t
bf20: 6f 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20  o fix a problem 
bf30: 77 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e  with priority in
bf40: 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c  version..** Appl
bf50: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
bf60: 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65  <em>not</em> use
bf70: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
bf80: 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ol..**.** <li>[[
bf90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50  SQLITE_FCNTL_ZIP
bfa0: 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  VFS]].** The [SQ
bfb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46  LITE_FCNTL_ZIPVF
bfc0: 53 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70  S] opcode is imp
bfd0: 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76  lemented by zipv
bfe0: 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68  fs only. All oth
bff0: 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64  er.** VFS should
c000: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e   return SQLITE_N
c010: 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73  OTFOUND for this
c020: 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c   opcode..**.** <
c030: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c040: 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b  L_RBU]].** The [
c050: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55  SQLITE_FCNTL_RBU
c060: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
c070: 65 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73  emented by the s
c080: 70 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20  pecial VFS used 
c090: 62 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78  by.** the RBU ex
c0a0: 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41  tension only.  A
c0b0: 6c 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f  ll other VFS sho
c0c0: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
c0d0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a  E_NOTFOUND for.*
c0e0: 2a 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20  * this opcode.  
c0f0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65  .** </ul>.*/.#de
c100: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c110: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20  L_LOCKSTATE     
c120: 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
c130: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c140: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
c150: 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  LE       2.#defi
c160: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c170: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
c180: 45 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  E       3.#defin
c190: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
c1a0: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
c1b0: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
c1c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49   SQLITE_FCNTL_SI
c1d0: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20  ZE_HINT         
c1e0: 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
c1f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
c200: 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  NK_SIZE         
c210: 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
c220: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
c230: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
c240: 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
c250: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
c260: 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20  OMITTED         
c270: 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
c280: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
c290: 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20  AV_RETRY        
c2a0: 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
c2b0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
c2c0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
c2d0: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
c2e0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
c2f0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
c300: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
c310: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20  _FCNTL_VFSNAME  
c320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32                12
c330: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c340: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
c350: 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a  OVERWRITE    13.
c360: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c370: 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20  CNTL_PRAGMA     
c380: 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23              14.#
c390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c3a0: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20  NTL_BUSYHANDLER 
c3b0: 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64             15.#d
c3c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c3d0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20  TL_TEMPFILENAME 
c3e0: 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65            16.#de
c3f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c400: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20  L_MMAP_SIZE     
c410: 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66           18.#def
c420: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c430: 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20  _TRACE          
c440: 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69          19.#defi
c450: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c460: 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20  HAS_MOVED       
c470: 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e         20.#defin
c480: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
c490: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
c4a0: 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65        21.#define
c4b0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f   SQLITE_FCNTL_CO
c4c0: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20  MMIT_PHASETWO   
c4d0: 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20       22.#define 
c4e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c4f0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20  32_SET_HANDLE   
c500: 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53      23.#define S
c510: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f  QLITE_FCNTL_WAL_
c520: 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  BLOCK           
c530: 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51     24.#define SQ
c540: 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46  LITE_FCNTL_ZIPVF
c550: 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  S               
c560: 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    25.#define SQL
c570: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20  ITE_FCNTL_RBU   
c580: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c590: 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   26.#define SQLI
c5a0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49  TE_FCNTL_VFS_POI
c5b0: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
c5c0: 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  27.#define SQLIT
c5d0: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
c5e0: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32  POINTER        2
c5f0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
c600: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54  _FCNTL_WIN32_GET
c610: 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39  _HANDLE       29
c620: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c630: 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20  FCNTL_PDB       
c640: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 30 0a               30.
c650: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e  ./* deprecated n
c660: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ames */.#define 
c670: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
c680: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
c690: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
c6a0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
c6b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
c6c0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
c6d0: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
c6e0: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
c6f0: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
c700: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
c710: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46          SQLITE_F
c720: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a  CNTL_LAST_ERRNO.
c730: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c740: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
c750: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
c760: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
c770: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
c780: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
c790: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
c7a0: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
c7b0: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
c7c0: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
c7d0: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
c7e0: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
c7f0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
c800: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
c810: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
c820: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
c830: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
c840: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
c850: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
c860: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
c870: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
c880: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
c890: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
c8a0: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
c8b0: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
c8c0: 50 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65  PI3REF: Loadable
c8d0: 20 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b   Extension Thunk
c8e0: 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
c8f0: 20 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73   to the opaque s
c900: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
c910: 6e 65 73 20 73 74 72 75 63 74 75 72 65 20 69 73  nes structure is
c920: 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68   passed as.** th
c930: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
c940: 72 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74  r to entry point
c950: 73 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65  s of [loadable e
c960: 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69  xtensions].  Thi
c970: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d  s.** structure m
c980: 75 73 74 20 62 65 20 74 79 70 65 64 65 66 65 64  ust be typedefed
c990: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72   in order to wor
c9a0: 6b 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65  k around compile
c9b0: 72 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e  r warnings.** on
c9c0: 20 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e   some platforms.
c9d0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
c9e0: 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ct sqlite3_api_r
c9f0: 6f 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f  outines sqlite3_
ca00: 61 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f  api_routines;../
ca10: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
ca20: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65  S Interface Obje
ca30: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
ca40: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
ca50: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
ca60: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
ca70: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
ca80: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
ca90: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
caa0: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
cab0: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
cac0: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
cad0: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
cae0: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
caf0: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20   file system".  
cb00: 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20  See.** the [VFS 
cb10: 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74  | VFS documentat
cb20: 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72  ion] for further
cb30: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
cb40: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66  .** The value of
cb50: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
cb60: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79  eld is initially
cb70: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61   1 but may be la
cb80: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72  rger in.** futur
cb90: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
cba0: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  Lite.  Additiona
cbb0: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  l fields may be 
cbc0: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73  appended to this
cbd0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20  .** object when 
cbe0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
cbf0: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e  ue is increased.
cc00: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
cc10: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
cc20: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
cc30: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
cc40: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  n the transactio
cc50: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c  n between.** SQL
cc60: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
cc70: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20  9 and 3.6.0 and 
cc80: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e  yet the iVersion
cc90: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a   field was not.*
cca0: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  * modified..**.*
ccb0: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
ccc0: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
ccd0: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
cce0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
ccf0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
cd00: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
cd10: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
cd20: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
cd30: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
cd40: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
cd50: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
cd60: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
cd70: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
cd80: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
cd90: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
cda0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
cdb0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
cdc0: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
cdd0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
cde0: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
cdf0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
ce00: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
ce10: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
ce20: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
ce30: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
ce40: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
ce50: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
ce60: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
ce70: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
ce80: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
ce90: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
cea0: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
ceb0: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
cec0: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
ced0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
cee0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
cef0: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
cf00: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
cf10: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
cf20: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
cf30: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
cf40: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
cf50: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
cf60: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
cf70: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
cf80: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
cf90: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
cfa0: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
cfb0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
cfc0: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
cfd0: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
cfe0: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
cff0: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
d000: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
d010: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
d020: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
d030: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
d040: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
d050: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
d060: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
d070: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74  Open]].** ^SQLit
d080: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
d090: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
d0a0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
d0b0: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
d0c0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
d0d0: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
d0e0: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
d0f0: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
d100: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
d110: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
d120: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
d130: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
d140: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
d150: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
d160: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
d170: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
d180: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
d190: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e  han.** 11 alphan
d1a0: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
d1b0: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
d1c0: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
d1d0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
d1e0: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
d1f0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
d200: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
d210: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
d220: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
d230: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
d240: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
d250: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
d260: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
d270: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
d280: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
d290: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
d2a0: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
d2b0: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
d2c0: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
d2d0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
d2e0: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
d2f0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
d300: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
d310: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
d320: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
d330: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
d340: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
d350: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
d360: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
d370: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
d380: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
d390: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
d3a0: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
d3b0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
d3c0: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
d3d0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
d3e0: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
d3f0: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
d400: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
d410: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
d420: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
d430: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
d440: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
d450: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
d460: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
d470: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
d480: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
d490: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
d4a0: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
d4b0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
d4c0: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
d4d0: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
d4e0: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
d4f0: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
d500: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
d510: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
d520: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
d530: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
d540: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
d550: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
d560: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
d570: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
d580: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
d590: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
d5a0: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
d5b0: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
d5c0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
d5d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d5e0: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
d5f0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
d600: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
d610: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d620: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
d630: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d640: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
d650: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d660: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
d670: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
d680: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
d690: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
d6a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
d6b0: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
d6c0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d6d0: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
d6e0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
d6f0: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
d700: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
d710: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
d720: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
d730: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
d740: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
d750: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
d760: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
d770: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
d780: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
d790: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
d7a0: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
d7b0: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
d7c0: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
d7d0: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
d7e0: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
d7f0: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
d800: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
d810: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
d820: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
d830: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
d840: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
d850: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
d860: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
d870: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
d880: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
d890: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
d8a0: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
d8b0: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
d8c0: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
d8d0: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
d8e0: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
d8f0: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
d900: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
d910: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
d920: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
d930: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
d940: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
d950: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
d960: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
d970: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
d980: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
d990: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
d9a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
d9b0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
d9c0: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
d9d0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
d9e0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
d9f0: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
da00: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
da10: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
da20: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
da30: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
da40: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
da50: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
da60: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
da70: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
da80: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
da90: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
daa0: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
dab0: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
dac0: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
dad0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
dae0: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
daf0: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
db00: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
db10: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
db20: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
db30: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
db40: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
db50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
db60: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
db70: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
db80: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
db90: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
dba0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
dbb0: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
dbc0: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
dbd0: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
dbe0: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
dbf0: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
dc00: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
dc10: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
dc20: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
dc30: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
dc40: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
dc50: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
dc60: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
dc70: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
dc80: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
dc90: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
dca0: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
dcb0: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
dcc0: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
dcd0: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
dce0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
dcf0: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
dd00: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
dd10: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
dd20: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
dd30: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
dd40: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
dd50: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
dd60: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
dd70: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
dd80: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
dd90: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
dda0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
ddb0: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
ddc0: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
ddd0: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
dde0: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
ddf0: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
de00: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
de10: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
de20: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
de30: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
de40: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
de50: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
de60: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
de70: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
de80: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
de90: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
dea0: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54  .xAccess]].** ^T
deb0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
dec0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
ded0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
dee0: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
def0: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
df00: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
df10: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
df20: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
df30: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
df40: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
df50: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
df60: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
df70: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
df80: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
df90: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
dfa0: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
dfb0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
dfc0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
dfd0: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
dfe0: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
dff0: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
e000: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
e010: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
e020: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
e030: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
e040: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
e050: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
e060: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
e070: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
e080: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
e090: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
e0a0: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
e0b0: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
e0c0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
e0d0: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
e0e0: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
e0f0: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
e100: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
e110: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
e120: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
e130: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
e140: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
e150: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
e160: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
e170: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
e180: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
e190: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
e1a0: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
e1b0: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
e1c0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
e1d0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
e1e0: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
e1f0: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
e200: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
e210: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
e220: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
e230: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
e240: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
e250: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
e260: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
e270: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
e280: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
e290: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
e2a0: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
e2b0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
e2c0: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
e2d0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
e2e0: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
e2f0: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
e300: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
e310: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
e320: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
e330: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
e340: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
e350: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
e360: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
e370: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
e380: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
e390: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
e3a0: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
e3b0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
e3c0: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
e3d0: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
e3e0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
e3f0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
e400: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
e410: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
e420: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
e430: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
e440: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
e450: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
e460: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
e470: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
e480: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
e490: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
e4a0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
e4b0: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
e4c0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
e4d0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
e4e0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
e4f0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
e500: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
e510: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
e520: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
e530: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
e540: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
e550: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
e560: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
e570: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
e580: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
e590: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
e5a0: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
e5b0: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
e5c0: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
e5d0: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
e5e0: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
e5f0: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
e600: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
e610: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
e620: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
e630: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
e640: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
e650: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
e660: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
e670: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
e680: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
e690: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
e6a0: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
e6b0: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
e6c0: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
e6d0: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
e6e0: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
e6f0: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
e700: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
e710: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
e720: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
e730: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
e740: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
e750: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
e760: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
e770: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
e780: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
e790: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
e7a0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
e7b0: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
e7c0: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
e7d0: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
e7e0: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
e7f0: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
e800: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
e810: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
e820: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
e830: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
e840: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
e850: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
e860: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
e870: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
e880: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
e890: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
e8a0: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
e8b0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
e8c0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
e8d0: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
e8e0: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
e8f0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
e900: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
e910: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
e920: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
e930: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
e940: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
e950: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
e960: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
e970: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
e980: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
e990: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
e9a0: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
e9b0: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
e9c0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
e9d0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
e9e0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
e9f0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
ea00: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
ea10: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
ea20: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
ea30: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
ea40: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
ea50: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
ea60: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
ea70: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
ea80: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
ea90: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
eaa0: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
eab0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
eac0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
ead0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
eae0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
eaf0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
eb00: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
eb10: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
eb20: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
eb30: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
eb40: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
eb50: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
eb60: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
eb70: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
eb80: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
eb90: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
eba0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
ebb0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
ebc0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
ebd0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
ebe0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
ebf0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
ec00: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ec10: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
ec20: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
ec30: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ec40: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
ec50: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
ec60: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
ec70: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
ec80: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
ec90: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
eca0: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
ecb0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ecc0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
ecd0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
ece0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
ecf0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
ed00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
ed10: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
ed20: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
ed30: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
ed40: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
ed50: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
ed60: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
ed70: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
ed80: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
ed90: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
eda0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
edb0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
edc0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
edd0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
ede0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
edf0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
ee00: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
ee10: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
ee20: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
ee30: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
ee40: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
ee50: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
ee60: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
ee70: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
ee80: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
ee90: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
eea0: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
eeb0: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
eec0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
eed0: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
eee0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
eef0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
ef00: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ef10: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
ef20: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
ef30: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
ef40: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
ef50: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
ef60: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ef70: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
ef80: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
ef90: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
efa0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
efb0: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
efc0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
efd0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
efe0: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
eff0: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
f000: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
f010: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
f020: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
f030: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
f040: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
f050: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
f060: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
f070: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
f080: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
f090: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
f0a0: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
f0b0: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
f0c0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
f0d0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
f0e0: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
f0f0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
f100: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
f110: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
f120: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
f130: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
f140: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
f150: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
f160: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
f170: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
f180: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
f190: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
f1a0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
f1b0: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
f1c0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
f1d0: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
f1e0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
f1f0: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
f200: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
f210: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
f220: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
f230: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
f240: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
f250: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
f260: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
f270: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
f280: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
f290: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
f2a0: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
f2b0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
f2c0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
f2d0: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
f2e0: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
f2f0: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
f300: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
f310: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
f320: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
f330: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
f340: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
f350: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
f360: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
f370: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
f380: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
f390: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
f3a0: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
f3b0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f3c0: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
f3d0: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
f3e0: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
f3f0: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
f400: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
f410: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
f420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
f430: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
f440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f450: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
f460: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
f470: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
f480: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
f490: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
f4a0: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
f4b0: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
f4c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f4d0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
f4e0: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
f4f0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
f500: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
f510: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
f520: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
f530: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
f540: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
f550: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
f560: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
f570: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
f580: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
f590: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
f5a0: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
f5b0: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
f5c0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
f5d0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
f5e0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
f5f0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
f600: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
f610: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
f620: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
f630: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
f640: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
f650: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
f660: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
f670: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
f680: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
f690: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
f6a0: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
f6b0: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
f6c0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
f6d0: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
f6e0: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
f6f0: 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73  en on the corres
f700: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
f710: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
f720: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
f730: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
f740: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
f750: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
f760: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
f770: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
f780: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
f790: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
f7a0: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
f7b0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
f7c0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
f7d0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
f7e0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
f7f0: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
f800: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
f810: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
f820: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
f830: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
f840: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
f850: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
f860: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
f870: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
f880: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
f890: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
f8a0: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
f8b0: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
f8c0: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
f8d0: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
f8e0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
f8f0: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
f900: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
f910: 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
f920: 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
f930: 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
f940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f950: 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
f960: 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
f970: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
f980: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
f990: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
f9a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f9b0: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
f9c0: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
f9d0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
f9e0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
f9f0: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
fa00: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
fa10: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
fa20: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
fa30: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
fa40: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
fa50: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
fa60: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
fa70: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
fa80: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
fa90: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
faa0: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
fab0: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
fac0: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
fad0: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
fae0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
faf0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
fb00: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
fb10: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
fb20: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fb30: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
fb40: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
fb50: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
fb60: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
fb70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
fb80: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
fb90: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
fba0: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
fbb0: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
fbc0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
fbd0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
fbe0: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
fbf0: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
fc00: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fc10: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
fc20: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
fc30: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
fc40: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
fc50: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
fc60: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
fc70: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
fc80: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
fc90: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
fca0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fcb0: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
fcc0: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
fcd0: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
fce0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
fcf0: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
fd00: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
fd10: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
fd20: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
fd30: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
fd40: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fd50: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
fd60: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
fd70: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
fd80: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
fd90: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
fda0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
fdb0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
fdc0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fdd0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
fde0: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
fdf0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fe00: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
fe10: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fe20: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
fe30: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
fe40: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
fe50: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
fe60: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
fe70: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
fe80: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
fe90: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
fea0: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
feb0: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
fec0: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
fed0: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
fee0: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
fef0: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
ff00: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
ff10: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
ff20: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
ff30: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
ff40: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
ff50: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
ff60: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
ff70: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
ff80: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
ff90: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
ffa0: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
ffb0: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
ffc0: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
ffd0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
ffe0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fff0: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
10000 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
10010 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
10020 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
10030 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
10040 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
10050 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
10060 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
10070 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
10080 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
10090 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
100a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
100b0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
100c0 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
100d0 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
100e0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
100f0 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
10100 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
10110 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
10120 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
10130 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10140 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
10150 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
10160 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
10170 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
10180 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
10190 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
101a0 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
101b0 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
101c0 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
101d0 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
101e0 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
101f0 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
10200 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
10210 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
10220 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10230 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
10240 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
10250 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
10260 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
10270 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
10280 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
10290 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
102a0 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
102b0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
102c0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
102d0 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
102e0 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
102f0 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
10300 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
10310 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
10320 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
10330 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
10340 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
10350 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
10360 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10370 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
10380 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
10390 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
103a0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
103b0 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
103c0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
103d0 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
103e0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
103f0 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
10400 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
10410 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10420 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
10430 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
10440 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
10450 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
10460 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
10470 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
10480 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
10490 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
104a0 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
104b0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
104c0 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
104d0 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
104e0 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
104f0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
10500 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
10510 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
10520 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
10530 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
10540 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
10550 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
10560 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
10570 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
10580 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
10590 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
105a0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
105b0 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
105c0 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
105d0 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
105e0 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
105f0 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
10600 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
10610 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
10620 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10630 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
10640 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
10650 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
10660 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
10670 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
10680 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
10690 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
106a0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
106b0 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
106c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
106d0 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
106e0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
106f0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
10700 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
10710 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
10720 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
10730 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10740 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
10750 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
10760 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
10770 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
10780 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
10790 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
107a0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
107b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
107c0 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
107d0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
107e0 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
107f0 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
10800 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
10810 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
10820 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
10830 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
10840 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
10850 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
10860 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
10870 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
10880 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
10890 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
108a0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
108b0 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
108c0 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
108d0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
108e0 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
108f0 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
10900 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
10910 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10920 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
10930 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
10940 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
10950 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
10960 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
10970 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
10980 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
10990 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
109a0 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
109b0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
109c0 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
109d0 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
109e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
109f0 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
10a00 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
10a10 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
10a20 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
10a30 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
10a40 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
10a50 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
10a60 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
10a70 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
10a80 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
10a90 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
10aa0 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
10ab0 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
10ac0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
10ad0 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
10ae0 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
10af0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
10b00 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
10b10 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
10b20 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
10b30 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
10b40 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
10b50 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
10b60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
10b70 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
10b80 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20  s..**.** <b>The 
10b90 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10ba0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
10bb0 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68  t threadsafe. Th
10bc0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
10bd0 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
10be0 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
10bf0 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
10c00 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
10c10 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
10c20 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
10c30 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c  g() is running.<
10c40 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  /b>.**.** The sq
10c50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10c60 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20  nterface.** may 
10c70 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
10c80 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
10c90 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
10ca0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
10cb0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
10cc0 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
10cd0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
10ce0 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
10cf0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
10d00 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
10d10 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
10d20 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
10d30 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
10d40 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
10d50 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
10d60 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
10d70 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
10d80 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
10d90 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
10da0 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
10db0 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
10dc0 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
10dd0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
10de0 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
10df0 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
10e00 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
10e10 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
10e20 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
10e30 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74  r.** [configurat
10e40 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
10e50 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
10e60 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
10e70 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
10e80 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
10e90 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
10ea0 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
10eb0 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66  ing on the [conf
10ec0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10ed0 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
10ee0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
10ef0 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
10f00 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
10f10 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
10f20 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
10f30 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
10f40 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
10f50 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
10f60 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
10f70 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
10f80 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
10f90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
10fa0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
10fb0 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ode]..*/.int sql
10fc0 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
10fd0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
10fe0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
10ff0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
11000 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
11010 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
11020 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
11030 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
11040 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
11050 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
11060 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
11070 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11080 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
11090 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
110a0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
110b0 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
110c0 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
110d0 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
110e0 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
110f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
11100 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
11110 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
11120 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
11130 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
11140 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
11150 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
11160 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
11170 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
11180 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
11190 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
111a0 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
111b0 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
111c0 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
111d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
111e0 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
111f0 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
11200 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
11210 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
11220 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
11230 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
11240 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
11250 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
11260 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
11270 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
11280 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
11290 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
112a0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
112b0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
112c0 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
112d0 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
112e0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
112f0 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
11300 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
11310 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
11320 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
11330 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
11340 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
11350 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
11360 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
11370 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
11380 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
11390 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
113a0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
113b0 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
113c0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
113d0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
113e0 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
113f0 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
11400 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
11410 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
11420 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
11430 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11440 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
11450 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
11460 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
11470 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
11480 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
11490 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
114a0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
114b0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
114c0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
114d0 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
114e0 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
114f0 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
11500 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
11510 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
11520 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
11530 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
11540 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
11550 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
11560 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
11570 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
11580 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
11590 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
115a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
115b0 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
115c0 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
115d0 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
115e0 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
115f0 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
11600 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
11610 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
11620 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
11630 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
11640 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
11650 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
11660 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
11670 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
11680 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
11690 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
116a0 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
116b0 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
116c0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
116d0 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
116e0 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
116f0 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
11700 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
11710 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
11720 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
11730 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
11740 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
11750 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
11760 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
11770 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
11780 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
11790 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
117a0 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
117b0 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
117c0 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
117d0 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
117e0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
117f0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
11800 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
11810 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
11820 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
11830 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
11840 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
11850 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
11860 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
11870 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
11880 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
11890 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
118a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
118b0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
118c0 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
118d0 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
118e0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
118f0 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
11900 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
11910 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
11920 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
11930 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
11940 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
11950 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
11960 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
11970 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
11980 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
11990 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
119a0 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
119b0 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
119c0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
119d0 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
119e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
119f0 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
11a00 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
11a10 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
11a20 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
11a30 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
11a40 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
11a50 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
11a60 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
11a70 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
11a80 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
11a90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
11aa0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
11ab0 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
11ac0 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
11ad0 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
11ae0 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
11af0 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
11b00 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
11b10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
11b20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
11b30 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
11b40 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
11b50 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
11b60 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
11b70 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
11b80 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
11b90 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
11ba0 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
11bb0 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
11bc0 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
11bd0 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
11be0 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
11bf0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
11c00 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
11c10 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
11c20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
11c30 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
11c40 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
11c50 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
11c60 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
11c70 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
11c80 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
11c90 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
11ca0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
11cb0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
11cc0 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
11cd0 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
11ce0 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
11cf0 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
11d00 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
11d10 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
11d20 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
11d30 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
11d40 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
11d50 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
11d60 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
11d70 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
11d80 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
11d90 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
11da0 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
11db0 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
11dc0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
11dd0 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
11de0 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
11df0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
11e00 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
11e10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
11e20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
11e30 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
11e40 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
11e50 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
11e60 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
11e70 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
11e80 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
11e90 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
11ea0 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
11eb0 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
11ec0 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
11ed0 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
11ee0 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
11ef0 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
11f00 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
11f10 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
11f20 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
11f30 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
11f40 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
11f50 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
11f60 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
11f70 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
11f80 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
11f90 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
11fa0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11fb0 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
11fc0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
11fd0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
11fe0 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
11ff0 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
12000 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
12010 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
12020 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
12030 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
12040 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
12050 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
12060 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
12070 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
12080 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
12090 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
120a0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
120b0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
120c0 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
120d0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
120e0 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
120f0 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
12100 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
12110 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
12120 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
12130 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
12140 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
12150 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
12160 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
12170 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
12180 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
12190 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
121a0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
121b0 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
121c0 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
121d0 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
121e0 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
121f0 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
12200 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
12210 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
12220 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
12230 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
12240 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
12250 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
12260 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
12270 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
12280 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12290 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
122a0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
122b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
122c0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
122d0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
122e0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
122f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12300 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
12310 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
12320 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
12330 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
12340 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12350 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
12360 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
12370 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
12380 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
12390 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
123a0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
123b0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
123c0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
123d0 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
123e0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
123f0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
12400 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
12410 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
12420 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
12430 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
12440 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12450 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
12460 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
12470 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12480 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
12490 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
124a0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
124b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
124c0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
124d0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
124e0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
124f0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
12500 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
12510 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
12520 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
12530 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
12540 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
12550 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
12560 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
12570 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
12580 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
12590 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
125a0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
125b0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
125c0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
125d0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
125e0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
125f0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
12600 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
12610 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
12620 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
12630 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
12640 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
12650 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
12660 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
12670 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
12680 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
12690 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
126a0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
126b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
126c0 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
126d0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
126e0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
126f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
12700 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
12710 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
12720 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
12730 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
12740 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
12750 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
12760 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
12770 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
12780 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
12790 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
127a0 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
127b0 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
127c0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
127d0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
127e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
127f0 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
12800 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
12810 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
12820 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
12830 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
12840 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
12850 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
12860 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
12870 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
12880 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
12890 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
128a0 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
128b0 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
128c0 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
128d0 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
128e0 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
128f0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
12900 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
12910 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12920 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
12930 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
12940 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12950 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
12960 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
12970 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
12980 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12990 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
129a0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
129b0 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
129c0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
129d0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
129e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
129f0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
12a00 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
12a10 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
12a20 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
12a30 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
12a40 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12a50 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
12a60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
12a70 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
12a80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12a90 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
12aa0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
12ab0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
12ac0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
12ad0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
12ae0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
12af0 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
12b00 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
12b10 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
12b20 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
12b30 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
12b40 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
12b50 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
12b60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12b70 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
12b80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
12b90 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
12ba0 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
12bb0 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
12bc0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12bd0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
12be0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
12bf0 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
12c00 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
12c10 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
12c20 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
12c30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
12c40 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
12c50 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
12c60 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
12c70 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
12c80 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
12c90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12ca0 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
12cb0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
12cc0 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
12cd0 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
12ce0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
12cf0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
12d00 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12d10 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
12d20 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
12d30 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
12d40 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
12d50 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
12d60 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
12d70 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
12d80 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
12d90 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
12da0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12db0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
12dc0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
12dd0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
12de0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12df0 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
12e00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
12e10 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12e20 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
12e30 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12e40 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
12e50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
12e60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
12e70 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
12e80 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12e90 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
12ea0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
12eb0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
12ec0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12ed0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
12ee0 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
12ef0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
12f00 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
12f10 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
12f20 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
12f30 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
12f40 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
12f50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
12f60 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
12f70 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
12f80 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
12f90 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
12fa0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
12fb0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12fc0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
12fd0 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
12fe0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
12ff0 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
13000 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
13010 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13020 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  G_GETMALLOC]] <d
13030 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13040 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
13050 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
13060 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
13070 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
13080 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13090 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
130a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
130b0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
130c0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
130d0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
130e0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
130f0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
13100 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
13110 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
13120 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
13130 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13140 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
13150 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
13160 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
13170 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
13180 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13190 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
131a0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
131b0 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
131c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
131d0 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
131e0 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
131f0 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
13200 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13210 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
13220 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
13230 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
13240 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
13250 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
13260 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f  NFIG_MEMSTATUS o
13270 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
13280 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
13290 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65  ype int,.** inte
132a0 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
132b0 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
132c0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
132d0 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
132e0 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  f.** memory allo
132f0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
13300 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
13310 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
13320 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69  istics are.** di
13330 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c  sabled, the foll
13340 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
13350 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
13360 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
13370 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
13380 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
13390 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
133a0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
133b0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
133c0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
133d0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
133e0 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
133f0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
13400 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  atus64()].**   <
13410 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
13420 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
13430 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
13440 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
13450 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
13460 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
13470 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
13480 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
13490 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
134a0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
134b0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
134c0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
134d0 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
134e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
134f0 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
13500 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13510 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
13520 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
13530 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
13540 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
13550 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
13560 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
13570 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
13580 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  or scratch memor
13590 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20  y.  ^(There are 
135a0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a  three arguments.
135b0 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ** to SQLITE_CON
135c0 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20  FIG_SCRATCH:  A 
135d0 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
135e0 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
135f0 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
13600 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
13610 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
13620 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
13630 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
13640 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
13650 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
13660 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
13670 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
13680 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29  llocations (N).)
13690 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ^.** The first a
136a0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
136b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
136c0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
136d0 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c  uffer.** of at l
136e0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
136f0 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
13700 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75  QLite will not u
13710 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  se more than one
13720 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
13730 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20   per thread..** 
13740 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76  ^SQLite will nev
13750 65 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72  er request a scr
13760 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74  atch buffer that
13770 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a   is more than 6.
13780 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74  ** times the dat
13790 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
137a0 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  .** ^If SQLite n
137b0 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
137c0 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
137d0 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
137e0 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
137f0 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
13800 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
13810 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
13820 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
13830 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
13840 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
13850 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20  ed.<p>.** ^When 
13860 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
13870 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f  provides any amo
13880 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d  unt of scratch m
13890 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53  emory using.** S
138a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
138b0 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f  ATCH, SQLite avo
138c0 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20  ids unnecessary 
138d0 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  large.** [sqlite
138e0 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c  3_malloc|heap al
138f0 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  locations]..** T
13900 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f  his can help [Ro
13910 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65  bson proof|preve
13920 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  nt memory alloca
13930 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64  tion failures] d
13940 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72  ue to heap.** fr
13950 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c  agmentation in l
13960 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64  ow-memory embedd
13970 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c  ed systems..** <
13980 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13990 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
139a0 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
139b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
139c0 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
139d0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
139e0 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74  IG_PAGECACHE opt
139f0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
13a00 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74  memory pool.** t
13a10 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
13a20 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  se for the datab
13a30 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
13a40 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
13a50 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
13a60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
13a70 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
13a80 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
13a90 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70  a no-op if an ap
13aa0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
13ab0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
13ac0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
13ad0 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
13ae0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
13af0 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54  _PCACHE2]..** ^T
13b00 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
13b10 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49  rguments to SQLI
13b20 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13b30 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  CHE: A pointer t
13b40 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67  o.** 8-byte alig
13b50 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d  ned memory (pMem
13b60 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  ), the size of e
13b70 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c  ach page cache l
13b80 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ine (sz),.** and
13b90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
13ba0 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a  ache lines (N)..
13bb0 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
13bc0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
13bd0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
13be0 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
13bf0 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
13c00 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
13c10 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75  2 and 65536) plu
13c20 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74  s some extra byt
13c30 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  es for each.** p
13c40 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
13c50 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
13c60 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62  a bytes needed b
13c70 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65  y the page heade
13c80 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  r.** can be dete
13c90 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51  rmined using [SQ
13ca0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13cb0 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49  HE_HDRSZ]..** ^I
13cc0 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
13cd0 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
13ce0 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
13cf0 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d  for the sz param
13d00 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65  eter to be large
13d10 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79  r than necessary
13d20 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61  .  The pMem.** a
13d30 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
13d40 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
13d50 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74  inter or a point
13d60 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  er to an 8-byte.
13d70 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b  ** aligned block
13d80 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74   of memory of at
13d90 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
13da0 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20  s, otherwise.** 
13db0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
13dc0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
13dd0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20  ..** ^When pMem 
13de0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
13df0 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20  ite will strive 
13e00 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  to use the memor
13e10 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f  y provided.** to
13e20 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61   satisfy page ca
13e30 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69  che needs, falli
13e40 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69  ng back to [sqli
13e50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66  te3_malloc()] if
13e60 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65  .** a page cache
13e70 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20   line is larger 
13e80 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72  than sz bytes or
13e90 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70   if all of the p
13ea0 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  Mem buffer.** is
13eb0 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e   exhausted..** ^
13ec0 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20  If pMem is NULL 
13ed0 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72  and N is non-zer
13ee0 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74  o, then each dat
13ef0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13f00 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74  .** does an init
13f10 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74  ial bulk allocat
13f20 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63  ion for page cac
13f30 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f  he memory.** fro
13f40 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
13f50 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20  c()] sufficient 
13f60 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65  for N cache line
13f70 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  s if N is positi
13f80 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32  ve or.** of -102
13f90 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69  4*N bytes if N i
13fa0 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49  s negative, . ^I
13fb0 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
13fc0 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
13fd0 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
13fe0 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
13ff0 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69  ded by the initi
14000 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  al.** allocation
14010 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f  , then SQLite go
14020 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
14030 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74  alloc()] separat
14040 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ely for each.** 
14050 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65  additional cache
14060 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   line. </dd>.**.
14070 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14080 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
14090 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
140a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
140b0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
140c0 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65  _HEAP option spe
140d0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
140e0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a  memory buffer .*
140f0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  * that SQLite wi
14100 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  ll use for all o
14110 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
14120 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14130 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20  needs.** beyond 
14140 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66  those provided f
14150 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
14160 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
14170 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  d.** [SQLITE_CON
14180 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
14190 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  ** ^The SQLITE_C
141a0 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f  ONFIG_HEAP optio
141b0 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
141c0 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
141d0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
141e0 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  h either [SQLITE
141f0 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
14200 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42   or [SQLITE_ENAB
14210 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20  LE_MEMSYS5] and 
14220 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
14230 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76  TE_ERROR] if inv
14240 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a  oked otherwise..
14250 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
14260 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
14270 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
14280 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74  EAP:.** An 8-byt
14290 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
142a0 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
142b0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
142c0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
142d0 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
142e0 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
142f0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
14300 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
14310 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
14320 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
14330 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
14340 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
14350 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
14360 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
14370 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
14380 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
14390 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
143a0 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
143b0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
143c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
143d0 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
143e0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
143f0 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
14400 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
14410 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
14420 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
14430 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
14440 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
14450 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
14460 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
14470 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
14480 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
14490 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
144a0 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
144b0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
144c0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
144d0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
144e0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
144f0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
14500 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
14510 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
14520 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
14530 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
14540 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
14550 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
14560 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
14570 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14580 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
14590 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
145a0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
145b0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
145c0 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20  IG_MUTEX option 
145d0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
145e0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
145f0 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
14600 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
14610 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
14620 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
14630 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
14640 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
14650 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
14660 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
14670 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
14680 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65  .** in place the
14690 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
146a0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
146b0 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
146c0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  kes a copy of.**
146d0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
146e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
146f0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
14700 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
14710 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
14720 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
14730 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
14740 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
14750 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
14760 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
14770 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14780 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
14790 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
147a0 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
147b0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
147c0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
147d0 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
147e0 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
147f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
14800 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
14810 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
14820 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14830 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
14840 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
14850 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
14860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14870 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
14880 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14890 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
148a0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
148b0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70  NFIG_GETMUTEX op
148c0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
148d0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
148e0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
148f0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
14900 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
14910 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
14920 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
14930 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
14940 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
14950 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
14960 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
14970 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
14980 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
14990 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
149a0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
149b0 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
149c0 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
149d0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
149e0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
149f0 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
14a00 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
14a10 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
14a20 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
14a30 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
14a40 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
14a50 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
14a60 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
14a70 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
14a80 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
14a90 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14aa0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
14ab0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
14ac0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
14ad0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
14ae0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
14af0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
14b00 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
14b10 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
14b20 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
14b30 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
14b40 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
14b50 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
14b60 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14b70 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
14b80 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  IDE]] <dt>SQLITE
14b90 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14ba0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
14bb0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
14bc0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74  IG_LOOKASIDE opt
14bd0 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
14be0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
14bf0 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65  ermine.** the de
14c00 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f  fault size of lo
14c10 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f  okaside memory o
14c20 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65  n each [database
14c30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
14c40 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
14c50 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
14c60 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
14c70 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
14c80 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
14c90 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
14ca0 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
14cb0 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
14cc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
14cd0 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e  )^  ^(SQLITE_CON
14ce0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a  FIG_LOOKASIDE.**
14cf0 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66   sets the <i>def
14d00 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
14d10 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
14d20 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
14d30 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69  OKASIDE].** opti
14d40 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  on to [sqlite3_d
14d50 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
14d60 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
14d70 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
14d80 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
14d90 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
14da0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
14db0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14dc0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14dd0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
14de0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
14df0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14e00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
14e10 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
14e20 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14e30 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
14e40 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
14e50 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
14e60 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14e70 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
14e80 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
14e90 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
14ea0 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
14eb0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
14ec0 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65  on.)^.** ^SQLite
14ed0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
14ee0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63   the [sqlite3_pc
14ef0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
14f00 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  bject.</dd>.**.*
14f10 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14f20 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c  G_GETPCACHE2]] <
14f30 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14f40 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e  _GETPCACHE2</dt>
14f50 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14f60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14f70 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
14f80 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14f90 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
14fa0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
14fb0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
14fc0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14fd0 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
14fe0 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75  ies of.** the cu
14ff0 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65  rrent page cache
15000 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
15010 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
15020 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
15030 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15040 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOG]] <dt>SQLITE
15050 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
15060 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
15070 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
15080 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
15090 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53   configure the S
150a0 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20  QLite.** global 
150b0 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20  [error log]..** 
150c0 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  (^The SQLITE_CON
150d0 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
150e0 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
150f0 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
15100 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
15110 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
15120 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
15130 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
15140 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
15150 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
15160 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
15170 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
15180 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
15190 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
151a0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
151b0 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
151c0 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
151d0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
151e0 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
151f0 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
15200 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
15210 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
15220 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
15230 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
15240 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
15250 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
15260 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
15270 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
15280 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
15290 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
152a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
152b0 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
152c0 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
152d0 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
152e0 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
152f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
15300 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
15310 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
15320 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
15330 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
15340 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
15350 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
15360 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
15370 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
15380 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
15390 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
153a0 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
153b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
153c0 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
153d0 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
153e0 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
153f0 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
15400 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
15410 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
15420 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
15430 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
15440 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
15450 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
15460 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
15470 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
15480 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
15490 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
154a0 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
154b0 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
154c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
154d0 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
154e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
154f0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
15500 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15510 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
15520 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15530 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e  FIG_URI.** <dd>^
15540 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
15550 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61  IG_URI option ta
15560 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15570 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
15580 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72  t..** If non-zer
15590 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  o, then URI hand
155a0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
155b0 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
155c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
155d0 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20  ro,.** then URI 
155e0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
155f0 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e  ally disabled.)^
15600 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e   ^If URI handlin
15610 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
15620 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
15630 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74  lenames passed t
15640 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
15650 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
15660 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  n_v2()],.** [sql
15670 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
15680 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
15690 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
156a0 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
156b0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
156c0 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
156d0 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
156e0 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
156f0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
15700 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
15710 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
15720 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
15730 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62  . ^If it is glob
15740 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
15750 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
15760 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
15770 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
15780 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
15790 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
157a0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
157b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
157c0 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61  pened. ^(By defa
157d0 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e  ult, URI handlin
157e0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
157f0 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64   disabled. The d
15800 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79  efault value may
15810 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63   be changed by c
15820 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68  ompiling with th
15830 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45  e.** [SQLITE_USE
15840 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66  _URI] symbol def
15850 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ined.)^.**.** [[
15860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
15870 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
15880 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
15890 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
158a0 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
158b0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
158c0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
158d0 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74  EX_SCAN option t
158e0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e  akes a single in
158f0 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  teger.** argumen
15900 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72  t which is inter
15910 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
15920 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ean in order to 
15930 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
15940 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  e.** the use of 
15950 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
15960 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
15970 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65  scans in the que
15980 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a  ry optimizer..**
15990 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
159a0 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69  tting is determi
159b0 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53  ned.** by the [S
159c0 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45  QLITE_ALLOW_COVE
159d0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
159e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
159f0 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22  tion, or is "on"
15a00 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70  .** if that comp
15a10 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
15a20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54  is omitted..** T
15a30 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69  he ability to di
15a40 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
15a50 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
15a60 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
15a70 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63   scans.** is bec
15a80 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72  ause some incorr
15a90 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61  ectly coded lega
15aa0 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  cy applications 
15ab0 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f  might malfunctio
15ac0 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70  n.** when the op
15ad0 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e  timization is en
15ae0 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e  abled.  Providin
15af0 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  g the ability to
15b00 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20  .** disable the 
15b10 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c  optimization all
15b20 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62  ows the older, b
15b30 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  uggy application
15b40 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   code to work.**
15b50 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20   without change 
15b60 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20  even with newer 
15b70 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
15b80 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  te..**.** [[SQLI
15b90 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15ba0 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ]] [[SQLITE_CONF
15bb0 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a  IG_GETPCACHE]].*
15bc0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15bd0 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53  FIG_PCACHE and S
15be0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15bf0 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54  PCACHE.** <dd> T
15c00 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65  hese options are
15c10 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68   obsolete and sh
15c20 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
15c30 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a   by new code..**
15c40 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e   They are retain
15c50 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
15c60 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62   compatibility b
15c70 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70  ut are now no-op
15c80 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
15c90 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15ca0 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64  G_SQLLOG]].** <d
15cb0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15cc0 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68  SQLLOG.** <dd>Th
15cd0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  is option is onl
15ce0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73  y available if s
15cf0 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  qlite is compile
15d00 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
15d10 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c  QLITE_ENABLE_SQL
15d20 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOG] pre-process
15d30 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  or macro defined
15d40 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  . The first argu
15d50 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62  ment should.** b
15d60 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
15d70 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
15d80 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  e void(*)(void*,
15d90 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63  sqlite3*,const c
15da0 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54  har*, int)..** T
15db0 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64  he second should
15dc0 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69   be of type (voi
15dd0 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63  d*). The callbac
15de0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  k is invoked by 
15df0 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
15e00 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65  n three separate
15e10 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
15e20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
15e30 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
15e40 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
15e50 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68  parameter. If th
15e60 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
15e70 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68  er is 0, then th
15e80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
15e90 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20  ction.** passed 
15ea0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
15eb0 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20  gument has just 
15ec0 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65  been opened. The
15ed0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
15ee0 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62  ** points to a b
15ef0 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67  uffer containing
15f00 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
15f10 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
15f20 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66  ile. If the.** f
15f30 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
15f40 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53  is 1, then the S
15f50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
15f60 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  t the third para
15f70 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20  meter.** points 
15f80 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  to has just been
15f90 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69   executed. Or, i
15fa0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
15fb0 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65  ameter is 2, the
15fc0 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74  n.** the connect
15fd0 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64  ion being passed
15fe0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
15ff0 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e  arameter is bein
16000 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a  g closed. The.**
16010 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
16020 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20   is passed NULL 
16030 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41  In this case.  A
16040 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69  n example of usi
16050 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69  ng this.** confi
16060 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
16070 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74  can be seen in t
16080 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e  he "test_sqllog.
16090 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69  c" source file i
160a0 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63  n.** the canonic
160b0 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  al SQLite source
160c0 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   tree.</dd>.**.*
160d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
160e0 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  G_MMAP_SIZE]].**
160f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16100 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20  IG_MMAP_SIZE.** 
16110 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  <dd>^SQLITE_CONF
16120 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b  IG_MMAP_SIZE tak
16130 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e  es two 64-bit in
16140 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69  teger (sqlite3_i
16150 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20  nt64) values.** 
16160 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66  that are the def
16170 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c  ault mmap size l
16180 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c  imit (the defaul
16190 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a  t setting for.**
161a0 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
161b0 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78  ze]) and the max
161c0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
161d0 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a  p size limit..**
161e0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
161f0 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65  tting can be ove
16200 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20  rridden by each 
16210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16220 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74  ion using.** eit
16230 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20  her the [PRAGMA 
16240 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61  mmap_size] comma
16250 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20  nd, or by using 
16260 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
16270 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
16280 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e  file control.  ^
16290 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c  (The maximum all
162a0 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a  owed mmap size.*
162b0 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74  * will be silent
162c0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20  ly truncated if 
162d0 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61  necessary so tha
162e0 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78  t it does not ex
162f0 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ceed the.** comp
16300 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d  ile-time maximum
16310 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62   mmap size set b
16320 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
16330 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  _MAX_MMAP_SIZE] 
16340 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
16350 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69  ion.)^.** ^If ei
16360 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f  ther argument to
16370 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
16380 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
16390 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  hat argument is.
163a0 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74  ** changed to it
163b0 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64  s compile-time d
163c0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efault..**.** [[
163d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
163e0 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a  N32_HEAPSIZE]].*
163f0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
16400 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
16410 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  ZE.** <dd>^The S
16420 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
16430 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69  32_HEAPSIZE opti
16440 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
16450 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
16460 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f  s.** compiled fo
16470 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74  r Windows with t
16480 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32  he [SQLITE_WIN32
16490 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f  _MALLOC] pre-pro
164a0 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20  cessor macro.** 
164b0 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45  defined. ^SQLITE
164c0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
164d0 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33  APSIZE takes a 3
164e0 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  2-bit unsigned i
164f0 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20  nteger value.** 
16500 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
16510 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
16520 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68  of the created h
16530 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  eap..**.** [[SQL
16540 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16550 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  E_HDRSZ]].** <dt
16560 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
16570 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c  CACHE_HDRSZ.** <
16580 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16590 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
165a0 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
165b0 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
165c0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
165d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
165e0 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65  nteger and write
165f0 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  s into that inte
16600 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ger the number o
16610 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73  f extra.** bytes
16620 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72   per page requir
16630 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65  ed for each page
16640 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   in [SQLITE_CONF
16650 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
16660 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  * The amount of 
16670 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75  extra space requ
16680 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20  ired can change 
16690 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
166a0 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61   compiler,.** ta
166b0 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61  rget platform, a
166c0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
166d0 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  n..**.** [[SQLIT
166e0 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d  E_CONFIG_PMASZ]]
166f0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16700 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c  ONFIG_PMASZ.** <
16710 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16720 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69  ONFIG_PMASZ opti
16730 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
16740 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
16750 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67  h.** is an unsig
16760 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
16770 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75  sets the "Minimu
16780 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20  m PMA Size" for 
16790 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65  the multithreade
167a0 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74  d.** sorter to t
167b0 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68  hat integer.  Th
167c0 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75  e default minimu
167d0 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65  m PMA Size is se
167e0 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  t by the.** [SQL
167f0 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a  ITE_SORTER_PMASZ
16800 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
16810 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65  ption.  New thre
16820 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64  ads are launched
16830 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68  .** to help with
16840 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73   sort operations
16850 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61   when multithrea
16860 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69  ded sorting.** i
16870 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67  s enabled (using
16880 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72   the [PRAGMA thr
16890 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61  eads] command) a
168a0 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  nd the amount of
168b0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62   content.** to b
168c0 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73  e sorted exceeds
168d0 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74   the page size t
168e0 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d  imes the minimum
168f0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47   of the.** [PRAG
16900 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73  MA cache_size] s
16910 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20  etting and this 
16920 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  value..**.** [[S
16930 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
16940 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a  TJRNL_SPILL]].**
16950 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16960 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
16970 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  L.** <dd>^The SQ
16980 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
16990 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f  JRNL_SPILL optio
169a0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
169b0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
169c0 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20  .** becomes the 
169d0 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e  [statement journ
169e0 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73  al] spill-to-dis
169f0 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a  k threshold.  .*
16a00 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75  * [Statement jou
16a10 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20  rnals] are held 
16a20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20  in memory until 
16a30 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62  their size (in b
16a40 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73  ytes).** exceeds
16a50 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c   this threshold,
16a60 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20   at which point 
16a70 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e  they are written
16a80 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20   to disk..** Or 
16a90 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64  if the threshold
16aa0 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e   is -1, statemen
16ab0 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61  t journals are a
16ac0 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78  lways held.** ex
16ad0 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d  clusively in mem
16ae0 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61  ory..** Since ma
16af0 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  ny statement jou
16b00 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f  rnals never beco
16b10 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e  me large, settin
16b20 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74  g the spill.** t
16b30 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61  hreshold to a va
16b40 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69  lue such as 64Ki
16b50 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65  B can greatly re
16b60 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20  duce the amount 
16b70 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72  of.** I/O requir
16b80 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74  ed to support st
16b90 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b  atement rollback
16ba0 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  ..** The default
16bb0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20   value for this 
16bc0 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72  setting is contr
16bd0 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  olled by the.** 
16be0 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c  [SQLITE_STMTJRNL
16bf0 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d  _SPILL] compile-
16c00 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
16c10 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
16c20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16c30 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
16c40 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
16c50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16c60 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
16c70 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
16c80 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16c90 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
16ca0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
16cb0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16cc0 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
16cd0 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
16ce0 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
16cf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16d00 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
16d10 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
16d20 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
16d30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16d40 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
16d50 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
16d60 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
16d70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16d80 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
16d90 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
16da0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
16db0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16dc0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
16dd0 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
16de0 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
16df0 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
16e00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16e10 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
16e20 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
16e30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16e40 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
16e50 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
16e60 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
16e70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16e80 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
16e90 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
16ea0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
16eb0 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
16ec0 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
16ed0 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
16ee0 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
16ef0 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
16f00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16f10 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
16f20 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
16f30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16f40 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
16f50 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20     14  /* no-op 
16f60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16f70 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
16f80 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d  HE    15  /* no-
16f90 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
16fa0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
16fb0 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
16fc0 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
16fd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16fe0 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20  ONFIG_URI       
16ff0 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f     17  /* int */
17000 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17010 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20  CONFIG_PCACHE2  
17020 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74      18  /* sqlit
17030 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
17040 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
17050 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17060 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a  PCACHE2   19  /*
17070 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
17080 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
17090 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
170a0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
170b0 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e  X_SCAN 20  /* in
170c0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
170d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
170e0 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78  G       21  /* x
170f0 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f  Sqllog, void* */
17100 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17110 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
17120 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74      22  /* sqlit
17130 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65  e3_int64, sqlite
17140 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69  3_int64 */.#defi
17150 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17160 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
17170 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20       23  /* int 
17180 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  nByte */.#define
17190 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
171a0 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20  CACHE_HDRSZ     
171b0 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70     24  /* int *p
171c0 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  sz */.#define SQ
171d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
171e0 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Z               
171f0 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20  25  /* unsigned 
17200 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65  int szPma */.#de
17210 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17220 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
17230 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e  L      26  /* in
17240 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a  t nByte */../*.*
17250 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
17260 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
17270 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
17280 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
17290 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
172a0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
172b0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
172c0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
172d0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
172e0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
172f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
17300 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
17310 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
17320 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
17330 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
17340 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
17350 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
17360 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
17370 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
17380 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
17390 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
173a0 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
173b0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
173c0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
173d0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
173e0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
173f0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
17400 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
17410 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
17420 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
17430 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
17440 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
17450 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
17460 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
17470 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
17480 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
17490 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
174a0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
174b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
174c0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
174d0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
174e0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
174f0 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
17500 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
17510 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
17520 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
17530 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
17540 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
17550 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
17560 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
17570 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
17580 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
17590 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
175a0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
175b0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
175c0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
175d0 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
175e0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
175f0 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
17600 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
17610 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
17620 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
17630 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
17640 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
17650 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
17660 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
17670 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
17680 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
17690 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
176a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
176b0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
176c0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
176d0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
176e0 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
176f0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
17700 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
17710 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
17720 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
17730 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
17740 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
17750 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
17760 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
17770 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
17780 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
17790 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
177a0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
177b0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
177c0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
177d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
177e0 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
177f0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17800 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
17810 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
17820 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
17830 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
17840 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
17850 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
17860 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
17870 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
17880 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
17890 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
178a0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
178b0 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
178c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
178d0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
178e0 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
178f0 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
17900 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
17910 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
17920 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
17930 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
17940 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
17950 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17960 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
17970 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
17980 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
17990 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
179a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
179b0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
179c0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
179d0 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
179e0 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
179f0 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
17a00 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
17a10 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
17a20 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
17a30 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
17a40 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
17a50 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
17a60 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
17a70 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
17a80 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
17a90 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
17aa0 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
17ab0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
17ac0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
17ad0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
17ae0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
17af0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
17b00 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
17b10 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
17b20 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
17b30 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
17b40 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
17b50 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
17b60 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
17b70 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
17b80 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
17b90 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
17ba0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
17bb0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
17bc0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
17bd0 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
17be0 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
17bf0 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
17c00 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
17c10 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17c20 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
17c30 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
17c40 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
17c50 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
17c60 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
17c70 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
17c80 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
17c90 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
17ca0 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
17cb0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
17cc0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
17cd0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
17ce0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
17cf0 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
17d00 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
17d10 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
17d20 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
17d30 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
17d40 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
17d50 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
17d60 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
17d70 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
17d80 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
17d90 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
17da0 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
17db0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
17dc0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17dd0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
17de0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
17df0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
17e00 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
17e10 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
17e20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
17e30 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
17e40 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
17e50 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
17e60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
17e70 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
17e80 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
17e90 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
17ea0 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
17eb0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
17ec0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
17ed0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
17ee0 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b  _ENABLE_FTS3_TOK
17ef0 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  ENIZER</dt>.** <
17f00 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
17f10 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
17f20 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
17f30 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a  e two-argument.*
17f40 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  * version of the
17f50 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72   [fts3_tokenizer
17f60 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69  ()] function whi
17f70 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68  ch is part of th
17f80 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c  e.** [FTS3] full
17f90 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67  -text search eng
17fa0 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a  ine extension..*
17fb0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
17fc0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
17fd0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
17fe0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17ff0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
18000 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
18010 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e  sable fts3_token
18020 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73  izer() or.** pos
18030 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
18040 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
18050 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
18060 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
18070 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a  g.** unchanged..
18080 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
18090 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
180a0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
180b0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
180c0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
180d0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
180e0 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65  hether fts3_toke
180f0 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  nizer is disable
18100 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
18110 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
18120 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
18130 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
18140 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
18150 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
18160 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69  se the new setti
18170 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
18180 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
18190 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
181a0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
181b0 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f  LOAD_EXTENSION</
181c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
181d0 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
181e0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
181f0 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  sable the [sqlit
18200 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
18210 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  n()].** interfac
18220 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20  e independently 
18230 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74  of the [load_ext
18240 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75  ension()] SQL fu
18250 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b  nction..** The [
18260 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
18270 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
18280 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 20   API enables or 
18290 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74 68  disables both th
182a0 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69  e.** C-API [sqli
182b0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
182c0 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53 51  on()] and the SQ
182d0 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64  L function [load
182e0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a  _extension()]..*
182f0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
18300 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
18310 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57   arguments..** W
18320 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 61 72  hen the first ar
18330 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 69  gument to this i
18340 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c 20 74  nterface is 1, t
18350 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41  hen only the C-A
18360 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64  PI is.** enabled
18370 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e   and the SQL fun
18380 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69  ction remains di
18390 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65 20  sabled.  If the 
183a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
183b0 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66  o.** this interf
183c0 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20 62  ace is 0, then b
183d0 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20 61 6e  oth the C-API an
183e0 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
183f0 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64 2e  on are disabled.
18400 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73 74  .** If the first
18410 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c   argument is -1,
18420 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73   then no changes
18430 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74 61   are made to sta
18440 74 65 20 6f 66 20 65 69 74 68 65 72 20 74 68 65  te of either the
18450 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 65  .** C-API or the
18460 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
18470 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
18480 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
18490 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
184a0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
184b0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
184c0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
184d0 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c  ether [sqlite3_l
184e0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
184f0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73   interface.** is
18500 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
18510 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  bled following t
18520 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
18530 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18540 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c  may.** be a NULL
18550 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 69   pointer, in whi
18560 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20  ch case the new 
18570 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
18580 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a  eported back..**
18590 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
185a0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
185b0 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e  _MAINDBNAME</dt>
185c0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
185d0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
185e0 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d 65   change the name
185f0 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20 64   of the "main" d
18600 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 6d  atabase.** schem
18610 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 72  a.  ^The sole ar
18620 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
18630 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 6e  ter to a constan
18640 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a  t UTF8 string.**
18650 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63 6f   which will beco
18660 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68 65 6d  me the new schem
18670 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 20  a name in place 
18680 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 4c  of "main".  ^SQL
18690 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ite.** does not 
186a0 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
186b0 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 65  he new main sche
186c0 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c 20  ma name string, 
186d0 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  so the applicati
186e0 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72  on.** must ensur
186f0 65 20 74 68 61 74 20 74 68 65 20 61 72 67 75 6d  e that the argum
18700 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ent passed into 
18710 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f 70  this DBCONFIG op
18720 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 65  tion is unchange
18730 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 72  d.** until after
18740 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
18750 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
18760 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
18770 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18780 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43  FIG_NO_CKPT_ON_C
18790 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LOSE</dt>.** <dd
187a0 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20  > Usually, when 
187b0 61 20 64 61 74 61 62 61 73 65 20 69 6e 20 77 61  a database in wa
187c0 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65 64  l mode is closed
187d0 20 6f 72 20 64 65 74 61 63 68 65 64 20 66 72 6f   or detached fro
187e0 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  m a .** database
187f0 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65 20   handle, SQLite 
18800 63 68 65 63 6b 73 20 69 66 20 74 68 69 73 20 77  checks if this w
18810 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74 68  ill mean that th
18820 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20 0a  ere are now no .
18830 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61  ** connections a
18840 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61 74  t all to the dat
18850 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69 74  abase. If so, it
18860 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65 63   performs a chec
18870 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72 61  kpoint .** opera
18880 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f 73  tion before clos
18890 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  ing the connecti
188a0 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  on. This option 
188b0 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a 2a  may be used to.*
188c0 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69 73 20  * override this 
188d0 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20 66  behaviour. The f
188e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70  irst parameter p
188f0 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70  assed to this op
18900 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61 6e  eration.** is an
18910 20 69 6e 74 65 67 65 72 20 2d 20 6e 6f 6e 2d 7a   integer - non-z
18920 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 63  ero to disable c
18930 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c  heckpoints-on-cl
18940 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74 68  ose, or zero (th
18950 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74 6f  e.** default) to
18960 20 65 6e 61 62 6c 65 20 74 68 65 6d 2e 20 54 68   enable them. Th
18970 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18980 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
18990 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
189a0 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77   into which is w
189b0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
189c0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
189d0 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e  r checkpoints-on
189e0 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20 62  -close.** have b
189f0 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20 30  een disabled - 0
18a00 20 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f 74   if they are not
18a10 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66 20   disabled, 1 if 
18a20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f 64  they are..** </d
18a30 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
18a40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18a50 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42  _DBCONFIG_MAINDB
18a60 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
18a70 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68  1000 /* const ch
18a80 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ar* */.#define S
18a90 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
18aa0 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 20  OOKASIDE        
18ab0 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69       1001 /* voi
18ac0 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
18ad0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
18ae0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
18af0 59 20 20 20 20 20 20 20 20 20 20 20 31 30 30 32  Y           1002
18b00 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
18b10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18b20 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
18b30 52 49 47 47 45 52 20 20 20 20 20 20 20 20 31 30  RIGGER        10
18b40 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  03 /* int int* *
18b50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18b60 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
18b70 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20  _FTS3_TOKENIZER 
18b80 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1004 /* 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 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f  LE_LOAD_EXTENSIO
18bc0 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e  N 1005 /* 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 4e 4f  LITE_DBCONFIG_NO
18bf0 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20  _CKPT_ON_CLOSE  
18c00 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20      1006 /* int 
18c10 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  int* */.../*.** 
18c20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
18c30 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
18c40 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
18c50 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
18c60 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
18c70 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
18c80 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
18c90 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
18ca0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
18cb0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
18cc0 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
18cd0 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
18ce0 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
18cf0 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
18d00 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
18d10 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
18d20 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
18d30 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
18d40 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
18d50 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
18d60 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
18d70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
18d80 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
18d90 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
18da0 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65  e3.**.** ^Each e
18db0 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c  ntry in most SQL
18dc0 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65  ite tables (exce
18dd0 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20  pt for [WITHOUT 
18de0 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a  ROWID] tables).*
18df0 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  * has a unique 6
18e00 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
18e10 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
18e20 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
18e30 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
18e40 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
18e50 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
18e60 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
18e70 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
18e80 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
18e90 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
18ea0 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
18eb0 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
18ec0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
18ed0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
18ee0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
18ef0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
18f00 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
18f10 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
18f20 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
18f30 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
18f40 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
18f50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
18f60 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
18f70 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 75  d(D) interface u
18f80 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  sually returns t
18f90 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a  he [rowid] of.**
18fa0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
18fb0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
18fc0 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69  ERT] into a rowi
18fd0 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74  d table or [virt
18fe0 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e  ual table].** on
18ff0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19000 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73  tion D. ^Inserts
19010 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
19020 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
19030 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64   not.** recorded
19040 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  . ^If no success
19050 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
19060 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20  to rowid tables 
19070 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
19080 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61  ed .** on the da
19090 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
190a0 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  n D, then sqlite
190b0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
190c0 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 0a  wid(D) returns .
190d0 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41  ** zero..**.** A
190e0 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e 67 20  s well as being 
190f0 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  set automaticall
19100 79 20 61 73 20 72 6f 77 73 20 61 72 65 20 69 6e  y as rows are in
19110 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61 74 61  serted into data
19120 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20  base.** tables, 
19130 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
19140 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
19150 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74 20 65  ion may be set e
19160 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20  xplicitly by.** 
19170 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73  [sqlite3_set_las
19180 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
19190 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72  ].**.** Some vir
191a0 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
191b0 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 49  mentations may I
191c0 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74 6f 20  NSERT rows into 
191d0 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61 73 0a  rowid tables as.
191e0 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69  ** part of commi
191f0 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  tting a transact
19200 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75  ion (e.g. to flu
19210 73 68 20 64 61 74 61 20 61 63 63 75 6d 75 6c 61  sh data accumula
19220 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a  ted in memory.**
19230 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74 68   to disk). In th
19240 69 73 20 63 61 73 65 20 73 75 62 73 65 71 75 65  is case subseque
19250 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68 69 73  nt calls to this
19260 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
19270 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73   the rowid.** as
19280 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
19290 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53  ese internal INS
192a0 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20  ERT operations, 
192b0 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f 20 0a  which leads to .
192c0 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65 20 72  ** unintuitive r
192d0 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61 6c 20  esults. Virtual 
192e0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
192f0 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20 77 72  tions that do wr
19300 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20  ite to rowid.** 
19310 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73 20 77  tables in this w
19320 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74 68 69  ay can avoid thi
19330 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72 65 73  s problem by res
19340 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69  toring the origi
19350 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61  nal .** rowid va
19360 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  lue using [sqlit
19370 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65  e3_set_last_inse
19380 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65 66 6f  rt_rowid()] befo
19390 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a  re returning .**
193a0 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20   control to the 
193b0 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  user..**.** ^(If
193c0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
193d0 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
193e0 67 67 65 72 20 74 68 65 6e 20 74 68 69 73 20 72  gger then this r
193f0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20  outine will .** 
19400 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69  return the [rowi
19410 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
19420 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ed row as long a
19430 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73  s the trigger is
19440 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e   .** running. On
19450 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 70  ce the trigger p
19460 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74 68 65  rogram ends, the
19470 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
19480 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
19490 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77  ine reverts to w
194a0 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72  hat it was befor
194b0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 77 61  e the trigger wa
194c0 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  s fired.)^.**.**
194d0 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68   ^An [INSERT] th
194e0 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
194f0 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
19500 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
19510 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
19520 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
19530 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
19540 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
19550 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
19560 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20  .  ^Thus INSERT 
19570 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
19580 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
19590 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
195a0 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
195b0 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
195c0 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
195d0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
195e0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
195f0 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
19600 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e  n fails.  ^(When
19610 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
19620 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
19630 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
19640 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
19650 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
19660 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
19670 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
19680 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
19690 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
196a0 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
196b0 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
196c0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
196d0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
196e0 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
196f0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
19700 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a  interface.)^.**.
19710 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
19720 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
19730 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
19740 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
19750 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
19760 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
19770 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
19780 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
19790 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
197a0 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f  is accessible to
197b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
197c0 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74  via the.** [last
197d0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20  _insert_rowid() 
197e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
197f0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
19800 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
19810 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
19820 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
19830 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19840 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
19850 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
19860 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
19870 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
19880 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
19890 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
198a0 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
198b0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
198c0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
198d0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
198e0 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
198f0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
19900 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
19910 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
19920 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c   or the new.** l
19930 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
19940 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  d]..*/.sqlite3_i
19950 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
19960 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
19970 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
19980 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 74   CAPI3REF: Set t
19990 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  he Last Insert R
199a0 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d  owid value..** M
199b0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
199c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
199d0 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74  _set_last_insert
199e0 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 74  _rowid(D, R) met
199f0 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 61  hod allows the a
19a00 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
19a10 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 72   set the value r
19a20 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c 69  eturned by calli
19a30 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  ng sqlite3_last_
19a40 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
19a50 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74  to R .** without
19a60 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f 77   inserting a row
19a70 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
19a80 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  se..*/.void sqli
19a90 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73  te3_set_last_ins
19aa0 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
19ab0 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  3*,sqlite3_int64
19ac0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19ad0 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
19ae0 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
19af0 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ified.** METHOD:
19b00 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
19b10 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
19b20 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
19b30 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
19b40 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a  d, inserted or.*
19b50 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  * deleted by the
19b60 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
19b70 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
19b80 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
19b90 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f  E.** statement o
19ba0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
19bb0 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66  onnection specif
19bc0 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20  ied by the only 
19bd0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45  parameter..** ^E
19be0 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
19bf0 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
19c00 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
19c10 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c  t modify the val
19c20 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
19c30 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  y this function.
19c40 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61  .**.** ^Only cha
19c50 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74  nges made direct
19c60 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54  ly by the INSERT
19c70 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
19c80 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  TE statement are
19c90 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d  .** considered -
19ca0 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   auxiliary chang
19cb0 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52  es caused by [CR
19cc0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
19cd0 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66  riggers], .** [f
19ce0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
19cf0 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d  ns] or [REPLACE]
19d00 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
19d10 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63  lution are not c
19d20 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43  ounted..** .** C
19d30 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
19d40 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
19d50 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e  epted by .** [IN
19d60 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
19d70 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72   | INSTEAD OF tr
19d80 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20  iggers] are not 
19d90 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61  counted. ^The va
19da0 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64  lue .** returned
19db0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
19dc0 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c  ges() immediatel
19dd0 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52  y after an INSER
19de0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a  T, UPDATE or .**
19df0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
19e00 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20  t run on a view 
19e10 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20  is always zero. 
19e20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
19e30 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61  e to real .** ta
19e40 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  bles are counted
19e50 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61  ..**.** Things a
19e60 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61  re more complica
19e70 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74  ted if the sqlit
19e80 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  e3_changes() fun
19e90 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63  ction is.** exec
19ea0 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69  uted while a tri
19eb0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20  gger program is 
19ec0 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61  running. This ma
19ed0 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a  y happen if the.
19ee0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20  ** program uses 
19ef0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
19f00 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72  QL function], or
19f10 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63   if some other c
19f20 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
19f30 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69  ion invokes sqli
19f40 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69  te3_changes() di
19f50 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61  rectly. Essentia
19f60 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e  lly:.** .** <ul>
19f70 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66  .**   <li> ^(Bef
19f80 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74  ore entering a t
19f90 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74  rigger program t
19fa0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19fb0 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73  d by.**        s
19fc0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
19fd0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76   function is sav
19fe0 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72  ed. After the tr
19ff0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a  igger program .*
1a000 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e  *        has fin
1a010 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69  ished, the origi
1a020 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73  nal value is res
1a030 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20  tored.)^.** .** 
1a040 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20    <li> ^(Within 
1a050 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
1a060 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55  m each INSERT, U
1a070 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45  PDATE and DELETE
1a080 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74   .**        stat
1a090 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76  ement sets the v
1a0a0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1a0b0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1a0c0 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70  () .**        up
1a0d0 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73  on completion as
1a0e0 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72   normal. Of cour
1a0f0 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77  se, this value w
1a100 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  ill not include 
1a110 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63  .**        any c
1a120 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64  hanges performed
1a130 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73   by sub-triggers
1a140 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33  , as the sqlite3
1a150 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
1a160 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c        value will
1a170 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65   be saved and re
1a180 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63  stored after eac
1a190 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61  h sub-trigger ha
1a1a0 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c  s run.)^.** </ul
1a1b0 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d  >.** .** ^This m
1a1c0 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65  eans that if the
1a1d0 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66   changes() SQL f
1a1e0 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69  unction (or simi
1a1f0 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20  lar) is used.** 
1a200 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53  by the first INS
1a210 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1a220 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1a230 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
1a240 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73  , it .** returns
1a250 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65   the value as se
1a260 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69  t when the calli
1a270 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67  ng statement beg
1a280 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  an executing..**
1a290 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20   ^If it is used 
1a2a0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72  by the second or
1a2b0 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68   subsequent such
1a2c0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
1a2d0 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20  n a trigger .** 
1a2e0 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c  program, the val
1a2f0 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c  ue returned refl
1a300 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20  ects the number 
1a310 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
1a320 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76   by the .** prev
1a330 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44  ious INSERT, UPD
1a340 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
1a350 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
1a360 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
1a370 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
1a380 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
1a390 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
1a3a0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
1a3b0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
1a3c0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
1a3d0 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
1a3e0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
1a3f0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
1a400 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
1a410 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
1a420 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a430 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
1a440 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
1a450 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
1a460 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1a470 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
1a480 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
1a490 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
1a4a0 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
1a4b0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
1a4c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
1a4d0 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
1a4e0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d  ws Modified.** M
1a4f0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1a500 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
1a510 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
1a520 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
1a530 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d  rows inserted, m
1a540 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65  odified or.** de
1a550 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e  leted by all [IN
1a560 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20  SERT], [UPDATE] 
1a570 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
1a580 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64  ements completed
1a590 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61  .** since the da
1a5a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a5b0 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e  n was opened, in
1a5c0 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78  cluding those ex
1a5d0 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72  ecuted as.** par
1a5e0 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f  t of trigger pro
1a5f0 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e  grams. ^Executin
1a600 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65  g any other type
1a610 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
1a620 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66  t.** does not af
1a630 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72  fect the value r
1a640 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1a650 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1a660 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e  ()..** .** ^Chan
1a670 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74  ges made as part
1a680 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   of [foreign key
1a690 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e   actions] are in
1a6a0 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a  cluded in the.**
1a6b0 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73   count, but thos
1a6c0 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  e made as part o
1a6d0 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  f REPLACE constr
1a6e0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  aint resolution 
1a6f0 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61  are.** not. ^Cha
1a700 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
1a710 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70  hat are intercep
1a720 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f  ted by INSTEAD O
1a730 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61  F triggers .** a
1a740 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
1a750 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  ** .** See also 
1a760 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
1a770 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
1a780 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
1a790 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
1a7a0 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
1a7b0 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
1a7c0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
1a7d0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
1a7e0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
1a7f0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
1a800 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a810 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
1a820 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1a830 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
1a840 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
1a850 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
1a860 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
1a870 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
1a880 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1a890 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
1a8a0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1a8b0 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
1a8c0 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
1a8d0 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48  ng Query.** METH
1a8e0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1a8f0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1a900 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
1a910 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
1a920 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
1a930 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
1a940 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
1a950 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
1a960 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
1a970 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
1a980 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
1a990 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
1a9a0 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
1a9b0 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
1a9c0 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
1a9d0 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
1a9e0 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
1a9f0 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
1aa00 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
1aa10 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
1aa20 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
1aa30 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
1aa40 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
1aa50 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
1aa60 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
1aa70 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
1aa80 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
1aa90 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
1aaa0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1aab0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
1aac0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1aad0 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
1aae0 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
1aaf0 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
1ab00 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1ab10 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
1ab20 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
1ab30 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
1ab40 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
1ab50 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
1ab60 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1ab70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
1ab80 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
1ab90 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
1aba0 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
1abb0 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
1abc0 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
1abd0 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
1abe0 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
1abf0 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
1ac00 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
1ac10 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
1ac20 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
1ac30 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
1ac40 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1ac50 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1ac60 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
1ac70 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
1ac80 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
1ac90 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
1aca0 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
1acb0 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
1acc0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
1acd0 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
1ace0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
1acf0 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
1ad00 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
1ad10 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
1ad20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1ad30 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
1ad40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ad50 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
1ad60 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
1ad70 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1ad80 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1ad90 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
1ada0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
1adb0 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
1adc0 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
1add0 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
1ade0 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
1adf0 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
1ae00 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
1ae10 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
1ae20 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1ae30 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
1ae40 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1ae50 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1ae60 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
1ae70 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
1ae80 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
1ae90 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
1aea0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
1aeb0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
1aec0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
1aed0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1aee0 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
1aef0 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
1af00 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1af10 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
1af20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
1af30 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
1af40 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1af50 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1af60 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1af70 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1af80 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69   returns..*/.voi
1af90 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
1afa0 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
1afb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1afc0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
1afd0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
1afe0 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20   Complete.**.** 
1aff0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1b000 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67  re useful during
1b010 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e   command-line in
1b020 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  put to determine
1b030 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   if the.** curre
1b040 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78  ntly entered tex
1b050 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20  t seems to form 
1b060 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
1b070 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69  tatement or.** i
1b080 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
1b090 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
1b0a0 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
1b0b0 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  text into.** SQL
1b0c0 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
1b0d0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
1b0e0 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68  s return 1 if th
1b0f0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
1b100 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
1b110 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
1b120 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74  tatement.  ^A st
1b130 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
1b140 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
1b150 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
1b160 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
1b170 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
1b180 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a   a prefix of a.*
1b190 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52  * well-formed CR
1b1a0 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
1b1b0 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f  tement.  ^Semico
1b1c0 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
1b1d0 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
1b1e0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
1b1f0 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
1b200 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
1b210 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
1b220 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
1b230 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
1b240 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
1b250 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
1b260 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
1b270 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
1b280 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
1b290 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
1b2a0 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a  .  ^Whitespace.*
1b2b0 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74  * and comments t
1b2c0 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66  hat follow the f
1b2d0 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61  inal semicolon a
1b2e0 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  re ignored..**.*
1b2f0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1b300 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68  s return 0 if th
1b310 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69  e statement is i
1b320 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20  ncomplete.  ^If 
1b330 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
1b340 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68  cation fails, th
1b350 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  en SQLITE_NOMEM 
1b360 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1b370 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1b380 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
1b390 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1b3a0 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20  ts thus.** will 
1b3b0 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
1b3c0 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
1b3d0 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ct SQL..**.** ^(
1b3e0 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
1b3f0 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
1b400 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1b410 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
1b420 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
1b430 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
1b440 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
1b450 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
1b460 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
1b470 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
1b480 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
1b490 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
1b4a0 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
1b4b0 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
1b4c0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1b4d0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
1b4e0 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
1b4f0 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
1b500 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
1b510 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
1b520 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
1b530 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  mplete.)^.**.** 
1b540 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
1b550 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
1b560 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
1b570 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
1b580 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
1b590 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
1b5a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
1b5b0 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61  e16()] must be a
1b5c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1b5d0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
1b5e0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
1b5f0 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73   order..*/.int s
1b600 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
1b610 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
1b620 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
1b630 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
1b640 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
1b650 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
1b660 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
1b670 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
1b680 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20  _BUSY Errors.** 
1b690 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d  KEYWORDS: {busy-
1b6a0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1b6b0 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d  } {busy handler}
1b6c0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1b6d0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
1b6e0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1b6f0 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69  ler(D,X,P) routi
1b700 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
1b710 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a  ck function X.**
1b720 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
1b730 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75  nvoked with argu
1b740 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a  ment P whenever.
1b750 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
1b760 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
1b770 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
1b780 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1b790 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1b7a0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e  nnection] D when
1b7b0 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
1b7c0 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
1b7d0 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b  s the table lock
1b7e0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ed..** The sqlit
1b7f0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1b800 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
1b810 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
1b820 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
1b830 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64  y_timeout()] and
1b840 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1b850 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  meout]..**.** ^I
1b860 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
1b870 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
1b880 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1b890 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
1b8a0 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
1b8b0 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
1b8c0 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20   lock.  ^If the 
1b8d0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
1b8e0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
1b8f0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1b900 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
1b910 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
1b920 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1b930 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1b940 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  o the busy handl
1b950 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
1b960 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
1b970 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
1b980 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
1b990 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
1b9a0 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68  _handler().  ^Th
1b9b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1b9c0 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79  t to.** the busy
1b9d0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
1b9e0 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
1b9f0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
1ba00 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
1ba10 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
1ba20 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f  ed previously fo
1ba30 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69  r the same locki
1ba40 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
1ba50 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
1ba60 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
1ba70 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
1ba80 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
1ba90 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
1baa0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
1bab0 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
1bac0 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74  is returned.** t
1bad0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
1bae0 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  n..** ^If the ca
1baf0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
1bb00 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
1bb10 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
1bb20 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
1bb30 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1bb40 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
1bb50 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
1bb60 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
1bb70 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
1bb80 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
1bb90 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
1bba0 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
1bbb0 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
1bbc0 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
1bbd0 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
1bbe0 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
1bbf0 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
1bc00 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
1bc10 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
1bc20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
1bc30 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
1bc40 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65  _BUSY].** to the
1bc50 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73   application ins
1bc60 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
1bc70 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61   the .** busy ha
1bc80 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
1bc90 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
1bca0 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
1bcb0 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
1bcc0 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
1bcd0 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
1bce0 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
1bcf0 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
1bd00 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
1bd10 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1bd20 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
1bd30 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
1bd40 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
1bd50 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
1bd60 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
1bd70 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
1bd80 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
1bd90 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
1bda0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
1bdb0 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
1bdc0 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
1bdd0 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
1bde0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
1bdf0 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
1be00 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
1be10 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
1be20 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
1be30 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
1be40 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
1be50 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
1be60 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
1be70 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
1be80 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
1be90 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
1bea0 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
1beb0 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
1bec0 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
1bed0 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
1bee0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
1bef0 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
1bf00 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
1bf10 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
1bf20 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
1bf30 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1bf40 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1bf50 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
1bf60 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
1bf70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1bf80 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
1bf90 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
1bfa0 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
1bfb0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
1bfc0 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
1bfd0 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
1bfe0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
1bff0 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65  meout()].** or e
1c000 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d  valuating [PRAGM
1c010 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e  A busy_timeout=N
1c020 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68  ] will change th
1c030 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65  e.** busy handle
1c040 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72  r and thus clear
1c050 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20   any previously 
1c060 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72  set busy handler
1c070 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79  ..**.** The busy
1c080 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1c090 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63   not take any ac
1c0a0 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69  tions which modi
1c0b0 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  fy the.** databa
1c0c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1c0d0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1c0e0 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e  usy handler.  In
1c0f0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a   other words,.**
1c100 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1c110 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  r is not reentra
1c120 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63  nt.  Any such ac
1c130 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20  tions.** result 
1c140 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
1c150 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20  avior..** .** A 
1c160 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
1c170 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
1c180 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c190 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61  ion.** or [prepa
1c1a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
1c1b0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1c1c0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
1c1d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
1c1e0 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
1c1f0 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  3*,int(*)(void*,
1c200 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  int),void*);../*
1c210 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
1c220 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
1c230 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1c240 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1c250 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
1c260 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1c270 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
1c280 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
1c290 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
1c2a0 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
1c2b0 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
1c2c0 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65  is locked.  ^The
1c2d0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
1c2e0 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
1c2f0 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
1c300 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
1c310 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
1c320 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
1c330 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20  ulated.  ^After 
1c340 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1c350 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1c360 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
1c370 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
1c380 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
1c390 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
1c3a0 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
1c3b0 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a  ITE_BUSY]..**.**
1c3c0 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72   ^Calling this r
1c3d0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
1c3e0 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
1c3f0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
1c400 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
1c410 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
1c420 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  s..**.** ^(There
1c430 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
1c440 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
1c450 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
1c460 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1c470 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
1c480 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
1c490 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
1c4a0 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
1c4b0 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
1c4c0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1c4d0 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
1c4e0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
1c4f0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
1c500 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
1c510 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
1c520 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
1c530 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73  so:  [PRAGMA bus
1c540 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e  y_timeout].*/.in
1c550 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
1c560 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
1c570 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
1c580 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
1c590 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
1c5a0 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
1c5b0 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ies.** METHOD: s
1c5c0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69  qlite3.**.** Thi
1c5d0 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
1c5e0 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
1c5f0 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
1c600 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1c610 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
1c620 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1c630 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
1c640 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
1c650 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
1c660 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
1c670 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
1c680 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
1c690 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1c6a0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
1c6b0 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
1c6c0 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
1c6d0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
1c6e0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
1c6f0 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
1c700 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
1c710 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
1c720 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
1c730 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
1c740 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
1c750 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
1c760 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
1c770 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
1c780 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
1c790 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
1c7a0 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
1c7b0 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
1c7c0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
1c7d0 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
1c7e0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
1c7f0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1c800 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
1c810 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
1c820 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1c830 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
1c840 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
1c850 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
1c860 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
1c870 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
1c880 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
1c890 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1c8a0 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
1c8b0 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
1c8c0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
1c8d0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
1c8e0 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
1c8f0 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
1c900 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
1c910 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
1c920 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
1c930 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
1c940 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
1c950 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1c960 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
1c970 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
1c980 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1c990 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
1c9a0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1c9b0 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
1c9c0 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
1c9d0 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
1c9e0 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
1c9f0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
1ca00 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1ca10 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
1ca20 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
1ca30 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1ca40 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
1ca50 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
1ca60 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1ca70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
1ca80 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
1ca90 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
1caa0 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
1cab0 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
1cac0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1cad0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1cae0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1caf0 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
1cb00 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
1cb10 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1cb20 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
1cb30 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
1cb40 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
1cb50 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
1cb60 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
1cb70 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
1cb80 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1cb90 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
1cba0 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
1cbb0 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
1cbc0 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
1cbd0 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
1cbe0 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
1cbf0 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
1cc00 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
1cc10 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
1cc20 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
1cc30 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
1cc40 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
1cc50 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
1cc60 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1cc70 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1cc80 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
1cc90 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1cca0 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
1ccb0 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
1ccc0 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
1ccd0 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
1cce0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1ccf0 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
1cd00 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1cd10 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
1cd20 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1cd30 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
1cd40 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1cd50 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
1cd60 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
1cd70 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
1cd80 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
1cd90 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
1cda0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1cdb0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1cdc0 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
1cdd0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
1cde0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
1cdf0 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
1ce00 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
1ce10 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1ce20 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
1ce30 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
1ce40 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
1ce50 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
1ce60 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
1ce70 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
1ce80 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1ce90 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
1cea0 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
1ceb0 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
1cec0 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
1ced0 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
1cee0 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
1cef0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
1cf00 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
1cf10 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
1cf20 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
1cf30 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1cf40 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
1cf50 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
1cf60 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
1cf70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1cf80 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
1cf90 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1cfa0 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
1cfb0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
1cfc0 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
1cfd0 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
1cfe0 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
1cff0 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
1d000 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
1d010 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
1d020 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
1d030 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
1d040 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1d050 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
1d060 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
1d070 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
1d080 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
1d090 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
1d0a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1d0b0 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
1d0c0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
1d0d0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
1d0e0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
1d0f0 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
1d100 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
1d110 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
1d120 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
1d130 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
1d140 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
1d150 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
1d160 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
1d170 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
1d180 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
1d190 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
1d1a0 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
1d1b0 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
1d1c0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
1d1d0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1d1e0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1d1f0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
1d200 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
1d210 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
1d220 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
1d230 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
1d240 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
1d250 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a  ar *zSql,     /*
1d260 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
1d270 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ated */.  char *
1d280 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20  **pazResult,    
1d290 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68  /* Results of th
1d2a0 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74  e query */.  int
1d2b0 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20   *pnRow,        
1d2c0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1d2d0 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
1d2e0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
1d2f0 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20  t *pnColumn,    
1d300 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1d310 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
1d320 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1d330 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73    char **pzErrms
1d340 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72  g       /* Error
1d350 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
1d360 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c  e */.);.void sql
1d370 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1d380 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
1d390 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d3a0 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
1d3b0 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
1d3c0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
1d3d0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
1d3e0 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
1d3f0 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
1d400 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
1d410 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
1d420 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
1d430 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1d440 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73  s understand mos
1d450 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20  t of the common 
1d460 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  K&R formatting o
1d470 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20  ptions,.** plus 
1d480 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1d490 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72  non-standard for
1d4a0 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62  mats, detailed b
1d4b0 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  elow..** Note th
1d4c0 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d  at some of the m
1d4d0 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d  ore obscure form
1d4e0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66  atting options f
1d4f0 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d  rom recent.** C-
1d500 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61 72 64  library standard
1d510 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72  s are omitted fr
1d520 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e  om this implemen
1d530 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  tation..**.** ^T
1d540 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
1d550 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
1d560 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
1d570 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
1d580 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
1d590 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
1d5a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
1d5b0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
1d5c0 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
1d5d0 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
1d5e0 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
1d5f0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
1d600 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1d610 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e  ].  ^Both routin
1d620 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
1d630 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
1d640 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1d650 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
1d660 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
1d670 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
1d680 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
1d690 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tring..**.** ^(T
1d6a0 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  he sqlite3_snpri
1d6b0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1d6c0 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
1d6d0 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
1d6e0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1d6f0 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
1d700 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
1d710 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
1d720 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
1d730 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1d740 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
1d750 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
1d760 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1d770 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
1d780 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
1d790 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
1d7a0 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
1d7b0 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
1d7c0 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e  ).)^  This is an
1d7d0 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
1d7e0 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
1d7f0 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
1d800 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
1d810 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1d820 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74  tibility.  ^(Not
1d830 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
1d840 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1d850 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
1d860 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
1d870 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1d880 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
1d890 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
1d8a0 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
1d8b0 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65  he buffer.)^  We
1d8c0 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
1d8d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
1d8e0 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
1d8f0 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
1d900 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
1d910 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
1d920 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
1d930 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1d940 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1d950 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
1d960 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
1d970 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
1d980 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  * ^As long as th
1d990 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
1d9a0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
1d9b0 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
1d9c0 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
1d9d0 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
1d9e0 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
1d9f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
1da00 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70   ^The first.** p
1da10 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
1da20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
1da30 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
1da40 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
1da50 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
1da60 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
1da70 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
1da80 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
1da90 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
1daa0 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
1dab0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
1dac0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73   ^The sqlite3_vs
1dad0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1dae0 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76  e is a varargs v
1daf0 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  ersion of sqlite
1db00 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a  3_snprintf()..**
1db10 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1db20 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
1db30 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
1db40 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
1db50 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
1db60 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
1db70 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
1db80 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
1db90 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
1dba0 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
1dbb0 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
1dbc0 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
1dbd0 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
1dbe0 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e  ", "%Q", "%w" an
1dbf0 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
1dc00 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f  **.** ^(The %q o
1dc10 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1dc20 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
1dc30 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
1dc40 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
1dc50 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
1dc60 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
1dc70 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
1dc80 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
1dc90 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
1dca0 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
1dcb0 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
1dcc0 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42  ng literal.)^  B
1dcd0 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
1dce0 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
1dcf0 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
1dd00 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
1dd10 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
1dd20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
1dd30 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
1dd40 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
1dd50 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
1dd60 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
1dd70 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
1dd80 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1dd90 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1dda0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
1ddb0 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
1ddc0 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
1ddd0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1dde0 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
1ddf0 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
1de00 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1de10 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1de20 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1de30 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1de40 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1de50 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1de60 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1de70 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
1de80 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1de90 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1dea0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1deb0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1dec0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1ded0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
1dee0 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
1def0 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
1df00 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
1df10 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
1df20 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
1df30 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
1df40 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1df50 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1df60 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1df70 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1df80 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
1df90 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
1dfa0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1dfb0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
1dfc0 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
1dfd0 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
1dfe0 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
1dff0 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
1e000 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
1e010 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1e020 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1e030 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1e040 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1e050 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
1e060 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
1e070 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1e080 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
1e090 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
1e0a0 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
1e0b0 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
1e0c0 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
1e0d0 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
1e0e0 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
1e0f0 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
1e100 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
1e110 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  teral..**.** ^(T
1e120 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72  he %Q option wor
1e130 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70  ks like %q excep
1e140 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73  t it also adds s
1e150 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f  ingle quotes aro
1e160 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69  und.** the outsi
1e170 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  de of the total 
1e180 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  string.  Additio
1e190 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61  nally, if the pa
1e1a0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a  rameter in the.*
1e1b0 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20  * argument list 
1e1c0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1e1d0 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65  r, %Q substitute
1e1e0 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c  s the text "NULL
1e1f0 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69  " (without.** si
1e200 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20  ngle quotes).)^ 
1e210 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
1e220 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
1e230 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1e240 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1e250 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1e260 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1e270 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1e280 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
1e290 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1e2a0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1e2b0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1e2c0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1e2d0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1e2e0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
1e2f0 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
1e300 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
1e310 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1e320 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
1e330 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
1e340 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
1e350 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
1e360 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ter..**.** ^(The
1e370 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%w" formatting
1e380 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20   option is like 
1e390 22 25 71 22 20 65 78 63 65 70 74 20 74 68 61 74  "%q" except that
1e3a0 20 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a   it expects to.*
1e3b0 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77  * be contained w
1e3c0 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f  ithin double-quo
1e3d0 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73  tes instead of s
1e3e0 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e  ingle quotes, an
1e3f0 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20  d it.** escapes 
1e400 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65  the double-quote
1e410 20 63 68 61 72 61 63 74 65 72 20 69 6e 73 74 65   character inste
1e420 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65  ad of the single
1e430 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63  -quote.** charac
1e440 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22  ter.)^  The "%w"
1e450 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1e460 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  on is intended f
1e470 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74  or safely insert
1e480 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64  ing.** table and
1e490 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e   column names in
1e4a0 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64  to a constructed
1e4b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
1e4c0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22  **.** ^(The "%z"
1e4d0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1e4e0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25  on works like "%
1e4f0 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a  s" but with the.
1e500 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
1e510 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
1e520 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
1e530 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
1e540 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
1e550 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1e560 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
1e570 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e   input string.)^
1e580 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
1e590 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
1e5a0 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
1e5b0 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
1e5c0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
1e5d0 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
1e5e0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1e5f0 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1e600 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68   char*, ...);.ch
1e610 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
1e620 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1e630 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1e640 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
1e650 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1e660 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
1e670 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
1e680 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
1e690 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
1e6a0 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
1e6b0 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
1e6c0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
1e6d0 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
1e6e0 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
1e6f0 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
1e700 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
1e710 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
1e720 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
1e730 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
1e740 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
1e750 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
1e760 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1e770 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
1e780 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
1e790 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1e7a0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1e7b0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1e7c0 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
1e7d0 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
1e7e0 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
1e7f0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1e800 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
1e810 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
1e820 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
1e830 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
1e840 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
1e850 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
1e860 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
1e870 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1e880 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
1e890 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
1e8a0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
1e8b0 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
1e8c0 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
1e8d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1e8e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e8f0 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75  _malloc64(N) rou
1e900 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20  tine works just 
1e910 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  like.** sqlite3_
1e920 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74  malloc(N) except
1e930 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e   that N is an un
1e940 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e  signed 64-bit in
1e950 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1e960 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d   of a signed 32-
1e970 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  bit integer..**.
1e980 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
1e990 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
1e9a0 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
1e9b0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
1e9c0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1e9d0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1e9e0 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
1e9f0 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
1ea00 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
1ea10 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
1ea20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
1ea30 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
1ea40 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
1ea50 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
1ea60 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
1ea70 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
1ea80 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
1ea90 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
1eaa0 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
1eab0 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
1eac0 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
1ead0 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
1eae0 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
1eaf0 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
1eb00 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
1eb10 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
1eb20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1eb30 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
1eb40 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
1eb50 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
1eb60 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
1eb70 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
1eb80 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
1eb90 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
1eba0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1ebb0 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1ebc0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
1ebd0 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
1ebe0 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
1ebf0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1ec00 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1ec10 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  loc()..**.** ^Th
1ec20 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
1ec30 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  c(X,N) interface
1ec40 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
1ec50 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
1ec60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1ec70 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73   X to be at leas
1ec80 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49  t N bytes..** ^I
1ec90 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65  f the X paramete
1eca0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1ecb0 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20  lloc(X,N).** is 
1ecc0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1ecd0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
1ece0 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
1ecf0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1ed00 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a  te3_malloc(N)..*
1ed10 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61  * ^If the N para
1ed20 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1ed30 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73  _realloc(X,N) is
1ed40 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
1ed50 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
1ed60 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
1ed70 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
1ed80 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1ed90 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71  _free(X)..** ^sq
1eda0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1edb0 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  N) returns a poi
1edc0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
1edd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
1ede0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
1edf0 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
1ee00 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
1ee10 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61  nt memory is ava
1ee20 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
1ee30 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
1ee40 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1ee50 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
1ee60 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
1ee70 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1ee80 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
1ee90 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
1eea0 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
1eeb0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1eec0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1eed0 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
1eee0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
1eef0 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  ed..** ^If sqlit
1ef00 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1ef10 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
1ef20 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20   N is positive, 
1ef30 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f  then the.** prio
1ef40 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1ef50 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
1ef60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
1ef70 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74  alloc64(X,N) int
1ef80 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68  erfaces works th
1ef90 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c  e same as.** sql
1efa0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1efb0 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
1efc0 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69  is a 64-bit unsi
1efd0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73  gned integer ins
1efe0 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d  tead.** of a 32-
1eff0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
1f000 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20  er..**.** ^If X 
1f010 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  is a memory allo
1f020 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c  cation previousl
1f030 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
1f040 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f050 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
1f060 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33  loc64(), sqlite3
1f070 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73  _realloc(), or s
1f080 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1f090 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  (), then.** sqli
1f0a0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
1f0b0 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
1f0c0 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c   that memory all
1f0d0 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73  ocation in bytes
1f0e0 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20  ..** ^The value 
1f0f0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1f100 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67  te3_msize(X) mig
1f110 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ht be larger tha
1f120 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  n the number.** 
1f130 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74  of bytes request
1f140 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c  ed when X was al
1f150 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20  located.  ^If X 
1f160 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1f170 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  r then.** sqlite
1f180 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
1f190 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70  ns zero.  If X p
1f1a0 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69  oints to somethi
1f1b0 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a  ng that is not.*
1f1c0 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  * the beginning 
1f1d0 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
1f1e0 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70  tion, or if it p
1f1f0 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65  oints to a forme
1f200 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d  rly.** valid mem
1f210 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1f220 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e  hat has now been
1f230 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65   freed, then the
1f240 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
1f250 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1f260 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
1f270 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66  d possibly harmf
1f280 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ul..**.** ^The m
1f290 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
1f2a0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1f2b0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
1f2c0 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
1f2d0 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e  3_malloc64(), an
1f2e0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
1f2f0 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  c64().** is alwa
1f300 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
1f310 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
1f320 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
1f330 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
1f340 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
1f350 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
1f360 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
1f370 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
1f380 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
1f390 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
1f3a0 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
1f3b0 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
1f3c0 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
1f3d0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
1f3e0 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
1f3f0 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
1f400 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
1f410 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
1f420 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
1f430 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
1f440 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
1f450 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
1f460 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
1f470 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
1f480 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
1f490 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
1f4a0 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
1f4b0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
1f4c0 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
1f4d0 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
1f4e0 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
1f4f0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
1f500 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
1f510 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
1f520 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
1f530 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
1f540 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
1f550 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
1f560 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
1f570 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
1f580 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
1f590 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
1f5a0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
1f5b0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
1f5c0 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
1f5d0 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
1f5e0 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
1f5f0 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
1f600 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
1f610 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
1f620 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
1f630 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
1f640 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
1f650 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
1f660 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1f670 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1f680 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
1f690 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
1f6a0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
1f6b0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
1f6c0 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
1f6d0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1f6e0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
1f6f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1f700 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
1f710 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
1f720 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
1f730 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
1f740 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
1f750 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
1f760 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
1f770 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
1f780 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
1f790 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1f7a0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
1f7b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
1f7c0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
1f7d0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
1f7e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
1f7f0 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e  oc64(sqlite3_uin
1f800 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  t64);.void *sqli
1f810 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
1f820 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  *, int);.void *s
1f830 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1f840 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f  (void*, sqlite3_
1f850 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  uint64);.void sq
1f860 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
1f870 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  );.sqlite3_uint6
1f880 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  4 sqlite3_msize(
1f890 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1f8a0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1f8b0 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
1f8c0 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
1f8d0 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
1f8e0 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
1f8f0 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
1f900 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
1f910 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
1f920 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
1f930 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
1f940 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1f950 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
1f960 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
1f970 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1f980 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
1f990 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
1f9a0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1f9b0 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
1f9c0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1f9d0 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
1f9e0 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
1f9f0 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
1fa00 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
1fa10 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
1fa20 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1fa30 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
1fa40 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1fa50 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
1fa60 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
1fa70 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
1fa80 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
1fa90 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
1faa0 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
1fab0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
1fac0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
1fad0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
1fae0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1faf0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1fb00 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
1fb10 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
1fb20 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
1fb30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1fb40 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1fb50 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
1fb60 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
1fb70 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
1fb80 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
1fb90 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
1fba0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
1fbb0 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
1fbc0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
1fbd0 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
1fbe0 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
1fbf0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
1fc00 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
1fc10 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1fc20 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
1fc30 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
1fc40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1fc50 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1fc60 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
1fc70 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
1fc80 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
1fc90 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
1fca0 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
1fcb0 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
1fcc0 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
1fcd0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
1fce0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1fcf0 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
1fd00 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1fd10 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1fd20 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
1fd30 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
1fd40 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
1fd50 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
1fd60 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
1fd70 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
1fd80 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
1fd90 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
1fda0 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
1fdb0 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
1fdc0 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
1fdd0 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
1fde0 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
1fdf0 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
1fe00 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
1fe10 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
1fe20 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
1fe30 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
1fe40 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
1fe50 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
1fe60 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
1fe70 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
1fe80 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
1fe90 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
1fea0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
1feb0 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
1fec0 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
1fed0 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
1fee0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
1fef0 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
1ff00 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
1ff10 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
1ff20 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70  r P..** ^The P p
1ff30 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20  arameter can be 
1ff40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1ff50 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72  **.** ^If this r
1ff60 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62  outine has not b
1ff70 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63  een previously c
1ff80 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20  alled or if the 
1ff90 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c  previous.** call
1ffa0 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e   had N less than
1ffb0 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70   one or a NULL p
1ffc0 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68  ointer for P, th
1ffd0 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a  en the PRNG is.*
1ffe0 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  * seeded using r
1fff0 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
20000 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ed from the xRan
20010 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
20020 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  f.** the default
20030 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
20040 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  bject..** ^If th
20050 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
20060 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
20070 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72  had an N of 1 or
20080 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e   more and a.** n
20090 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74  on-NULL P then t
200a0 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
200b0 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
200c0 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
200d0 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
200e0 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
200f0 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
20100 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
20110 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
20120 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
20130 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
20140 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
20150 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
20160 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
20170 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ks.** METHOD: sq
20180 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f 52 44  lite3.** KEYWORD
20190 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72 20 63  S: {authorizer c
201a0 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a 20 5e  allback}.**.** ^
201b0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
201c0 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
201d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
201e0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
201f0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
20200 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
20210 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
20220 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
20230 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
20240 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
20250 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
20260 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
20270 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
20280 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
20290 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
202a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
202b0 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
202c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
202d0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
202e0 61 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  are16()], [sqlit
202f0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
20300 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  )],.** and [sqli
20310 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
20320 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
20330 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
20340 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
20350 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
20360 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
20370 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
20380 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
20390 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
203a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
203b0 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
203c0 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
203d0 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
203e0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
203f0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
20400 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
20410 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
20420 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
20430 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
20440 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
20450 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
20460 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
20470 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
20480 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
20490 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
204a0 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
204b0 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
204c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
204d0 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
204e0 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
204f0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
20500 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
20510 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
20520 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
20530 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
20540 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
20550 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
20560 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
20570 72 65 70 61 72 65 5f 76 33 28 29 5d 20 6f 72 20  repare_v3()] or 
20580 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
20590 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
205a0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
205b0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
205c0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
205d0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
205e0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
205f0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
20600 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
20610 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
20620 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
20630 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
20640 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
20650 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
20660 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20670 33 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  3()] or equivale
20680 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
20690 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
206a0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
206b0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
206c0 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
206d0 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
206e0 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
206f0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
20700 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
20710 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20720 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
20730 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
20740 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
20750 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
20760 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
20770 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
20780 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
20790 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
207a0 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
207b0 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
207c0 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
207d0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
207e0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
207f0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
20800 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
20810 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
20820 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
20830 61 6c 6c 62 61 63 6b 20 61 72 65 20 65 69 74 68  allback are eith
20840 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  er NULL pointers
20850 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   or zero-termina
20860 74 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 74  ted strings.** t
20870 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
20880 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61  tional details a
20890 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
208a0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
208b0 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
208c0 73 20 6d 75 73 74 20 61 6c 77 61 79 73 20 62 65  s must always be
208d0 20 70 72 65 70 61 72 65 64 20 74 6f 20 65 6e 63   prepared to enc
208e0 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20 70 6f  ounter a NULL po
208f0 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a 2a 20  inter in any.** 
20900 6f 66 20 74 68 65 20 74 68 69 72 64 20 74 68 72  of the third thr
20910 6f 75 67 68 20 74 68 65 20 73 69 78 74 68 20 70  ough the sixth p
20920 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
20930 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63   authorization c
20940 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
20950 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
20960 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
20970 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
20980 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
20990 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
209a0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
209b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
209c0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
209d0 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
209e0 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
209f0 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
20a00 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
20a10 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
20a20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
20a30 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
20a40 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
20a50 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
20a60 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
20a70 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
20a80 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
20a90 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
20aa0 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
20ab0 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
20ac0 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ble..** ^When a 
20ad0 74 61 62 6c 65 20 69 73 20 72 65 66 65 72 65 6e  table is referen
20ae0 63 65 64 20 62 79 20 61 20 5b 53 45 4c 45 43 54  ced by a [SELECT
20af0 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d 6e 20  ] but no column 
20b00 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20 65 78  values are.** ex
20b10 74 72 61 63 74 65 64 20 66 72 6f 6d 20 74 68 61  tracted from tha
20b20 74 20 74 61 62 6c 65 20 28 66 6f 72 20 65 78 61  t table (for exa
20b30 6d 70 6c 65 20 69 6e 20 61 20 71 75 65 72 79 20  mple in a query 
20b40 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43 54 20  like.** "SELECT 
20b50 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20 74 61  count(*) FROM ta
20b60 62 22 29 20 74 68 65 6e 20 74 68 65 20 5b 53 51  b") then the [SQ
20b70 4c 49 54 45 5f 52 45 41 44 5d 20 61 75 74 68 6f  LITE_READ] autho
20b80 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
20b90 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  * is invoked onc
20ba0 65 20 66 6f 72 20 74 68 61 74 20 74 61 62 6c 65  e for that table
20bb0 20 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e 20 6e   with a column n
20bc0 61 6d 65 20 74 68 61 74 20 69 73 20 61 6e 20 65  ame that is an e
20bd0 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  mpty string..** 
20be0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
20bf0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
20c00 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
20c10 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
20c20 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
20c30 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
20c40 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
20c50 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
20c60 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
20c70 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
20c80 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
20c90 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
20ca0 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
20cb0 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
20cc0 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
20cd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
20ce0 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
20cf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
20d00 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
20d10 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
20d20 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
20d30 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
20d40 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
20d50 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
20d60 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
20d70 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
20d80 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
20d90 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
20da0 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
20db0 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
20dc0 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
20dd0 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
20de0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
20df0 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
20e00 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
20e10 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
20e20 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
20e30 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
20e40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
20e50 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
20e60 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
20e70 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
20e80 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
20e90 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
20ea0 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
20eb0 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
20ec0 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
20ed0 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
20ee0 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
20ef0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
20f00 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
20f10 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
20f20 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
20f30 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
20f40 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
20f50 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
20f60 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
20f70 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
20f80 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
20f90 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
20fa0 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
20fb0 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
20fc0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
20fd0 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
20fe0 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
20ff0 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
21000 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
21010 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
21020 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
21030 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
21040 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
21050 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
21060 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
21070 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
21080 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
21090 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
210a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
210b0 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
210c0 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
210d0 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
210e0 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
210f0 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
21100 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
21110 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
21120 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
21130 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
21140 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
21150 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
21160 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
21170 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
21180 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
21190 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
211a0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
211b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
211c0 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
211d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
211e0 65 5f 76 33 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v3()] and [sql
211f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
21200 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
21210 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
21220 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
21230 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
21240 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
21250 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
21260 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
21270 72 65 5f 76 33 28 29 5d 20 69 73 20 75 73 65 64  re_v3()] is used
21280 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
21290 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
212a0 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
212b0 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
212c0 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
212d0 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
212e0 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
212f0 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
21300 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
21310 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
21320 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
21330 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21340 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
21350 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
21360 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
21370 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
21380 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
21390 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
213a0 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
213b0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
213c0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
213d0 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
213e0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
213f0 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
21400 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
21410 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
21420 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
21430 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
21440 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
21450 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
21460 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
21470 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
21480 61 72 65 5f 76 33 28 29 20 74 6f 20 72 65 70 72  are_v3() to repr
21490 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
214a0 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
214b0 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
214c0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
214d0 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
214e0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
214f0 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
21500 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
21510 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
21520 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
21530 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
21540 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
21550 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
21560 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
21570 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
21580 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
21590 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
215a0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
215b0 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
215c0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
215d0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
215e0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
215f0 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
21600 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
21610 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
21620 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
21630 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
21640 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
21650 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
21660 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
21670 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
21680 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
21690 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
216a0 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
216b0 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
216c0 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73   a [conflict res
216d0 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a  olution mode].**
216e0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74   returned from t
216f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
21700 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
21710 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
21720 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
21730 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
21740 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
21750 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
21760 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21770 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
21780 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
21790 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
217a0 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
217b0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
217c0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
217d0 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
217e0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
217f0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
21800 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
21810 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
21820 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
21830 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
21840 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
21850 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
21860 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
21870 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
21880 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
21890 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
218a0 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
218b0 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
218c0 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
218d0 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
218e0 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
218f0 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
21900 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
21910 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
21920 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
21930 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
21940 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
21950 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
21960 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
21970 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
21980 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
21990 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
219a0 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
219b0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
219c0 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
219d0 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
219e0 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
219f0 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
21a00 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
21a10 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
21a20 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
21a30 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
21a40 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
21a50 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
21a60 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
21a70 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
21a80 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
21a90 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
21aa0 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
21ab0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
21ac0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21ad0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
21ae0 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
21af0 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
21b00 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
21b10 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
21b20 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
21b30 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
21b40 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
21b50 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
21b60 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
21b70 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
21b80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21b90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21ba0 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
21bb0 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
21bc0 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
21bd0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
21be0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
21bf0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
21c00 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
21c10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21c20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
21c30 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
21c40 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21c50 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21c60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21c70 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
21c80 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
21c90 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
21ca0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21cb0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21cc0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
21cd0 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
21ce0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
21cf0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21d00 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21d10 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
21d20 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
21d30 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
21d40 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21d50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21d60 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
21d70 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
21d80 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
21d90 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21da0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21db0 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
21dc0 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
21dd0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
21de0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
21df0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21e00 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
21e10 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
21e20 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
21e30 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21e40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21e50 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
21e60 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
21e70 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
21e80 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21e90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21ea0 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
21eb0 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
21ec0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
21ed0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
21ee0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
21ef0 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
21f00 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
21f10 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
21f20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21f30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
21f40 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
21f50 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
21f60 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
21f70 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21f80 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21f90 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
21fa0 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
21fb0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
21fc0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21fd0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
21fe0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
21ff0 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
22000 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
22010 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22020 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
22030 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
22040 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
22050 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22060 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22070 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
22080 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
22090 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
220a0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
220b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
220c0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
220d0 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
220e0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
220f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22100 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22110 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
22120 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
22130 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22140 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22150 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22160 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
22170 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
22180 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
22190 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
221a0 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
221b0 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
221c0 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
221d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
221e0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
221f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22200 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
22210 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
22220 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22230 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22240 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22250 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
22260 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
22270 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
22280 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22290 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
222a0 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
222b0 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
222c0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
222d0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
222e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
222f0 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
22300 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
22310 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
22320 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22330 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22340 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
22350 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
22360 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
22370 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22380 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
22390 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
223a0 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
223b0 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
223c0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
223d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
223e0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
223f0 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
22400 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22410 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22420 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
22430 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
22440 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
22450 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
22460 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22470 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
22480 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
22490 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
224a0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
224b0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
224c0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
224d0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
224e0 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
224f0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
22500 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
22510 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
22520 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
22530 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
22540 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
22550 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
22560 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
22570 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
22580 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
22590 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
225a0 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
225b0 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
225c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
225d0 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
225e0 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  sed */.#define S
225f0 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20  QLITE_RECURSIVE 
22600 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20             33   
22610 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
22620 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22630 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     */../*.** CAP
22640 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
22650 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
22660 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
22670 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
22680 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
22690 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 55  re deprecated. U
226a0 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
226b0 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65  trace_v2()] inte
226c0 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64  rface.** instead
226d0 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73   of the routines
226e0 20 64 65 73 63 72 69 62 65 64 20 68 65 72 65 2e   described here.
226f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
22700 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
22710 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
22720 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
22730 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
22740 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
22750 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
22760 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
22770 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
22780 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
22790 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
227a0 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
227b0 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
227c0 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
227d0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
227e0 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
227f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
22800 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
22810 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
22820 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
22830 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
22840 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
22850 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
22860 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
22870 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
22880 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
22890 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
228a0 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
228b0 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
228c0 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
228d0 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
228e0 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
228f0 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
22900 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
22910 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
22920 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
22930 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
22940 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  gger.)^.**.** Th
22950 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
22960 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
22970 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
22980 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
22990 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67  imit.** the leng
229a0 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  th of [bound par
229b0 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f  ameter] expansio
229c0 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20  n in the output 
229d0 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  of sqlite3_trace
229e0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ()..**.** ^The c
229f0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
22a00 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
22a10 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
22a20 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
22a30 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
22a40 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
22a50 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
22a60 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
22a70 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
22a80 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
22a90 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
22aa0 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
22ab0 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
22ac0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
22ad0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
22ae0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
22af0 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
22b00 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
22b10 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
22b20 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
22b30 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
22b40 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
22b50 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
22b60 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
22b70 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
22b80 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
22b90 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
22ba0 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
22bb0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
22bc0 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
22bd0 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
22be0 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
22bf0 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
22c00 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ck.  The.** sqli
22c10 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75  te3_profile() fu
22c20 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64  nction is consid
22c30 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
22c40 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a  l and is.** subj
22c50 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
22c60 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
22c70 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53   of SQLite..*/.S
22c80 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
22c90 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74   void *sqlite3_t
22ca0 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  race(sqlite3*,. 
22cb0 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28    void(*xTrace)(
22cc0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
22cd0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
22ce0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
22cf0 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
22d00 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
22d10 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
22d20 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
22d30 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
22d40 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
22d50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
22d60 20 54 72 61 63 65 20 45 76 65 6e 74 20 43 6f 64   Trace Event Cod
22d70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
22d80 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a  SQLITE_TRACE.**.
22d90 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
22da0 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c 61 73  ts identify clas
22db0 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20 74 68  ses of events th
22dc0 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f  at can be monito
22dd0 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  red.** using the
22de0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
22df0 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f  v2()] tracing lo
22e00 67 69 63 2e 20 20 54 68 65 20 74 68 69 72 64 20  gic.  The third 
22e10 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b  argument.** to [
22e20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
22e30 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64 20  ()] is an OR-ed 
22e40 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f  combination of o
22e50 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a  ne or more of.**
22e60 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
22e70 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68 65 20  onstants.  ^The 
22e80 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
22e90 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c  o the trace call
22ea0 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f  back.** is one o
22eb0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
22ec0 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a  constants..**.**
22ed0 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63 6f 6e   New tracing con
22ee0 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 61 64  stants may be ad
22ef0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
22f00 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  leases..**.** ^A
22f10 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
22f20 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d 65 6e  has four argumen
22f30 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c  ts: xCallback(T,
22f40 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20  C,P,X)..** ^The 
22f50 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  T argument is on
22f60 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  e of the integer
22f70 20 74 79 70 65 20 63 6f 64 65 73 20 61 62 6f 76   type codes abov
22f80 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67  e..** ^The C arg
22f90 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20  ument is a copy 
22fa0 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70  of the context p
22fb0 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
22fc0 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
22fd0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
22fe0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
22ff0 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64  )]..** The P and
23000 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65   X arguments are
23010 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20   pointers whose 
23020 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20  meanings depend 
23030 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  on T..**.** <dl>
23040 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
23050 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51  CE_STMT]] <dt>SQ
23060 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c  LITE_TRACE_STMT<
23070 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
23080 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
23090 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  T callback is in
230a0 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70 72 65  voked when a pre
230b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
230c0 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  ** first begins 
230d0 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73  running and poss
230e0 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20 74 69  ibly at other ti
230f0 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65 0a 2a  mes during the.*
23100 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  * execution of t
23110 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
23120 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73 20 61  ement, such as a
23130 74 20 74 68 65 20 73 74 61 72 74 20 6f 66 20 65  t the start of e
23140 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72 20 73  ach.** trigger s
23150 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20  ubprogram. ^The 
23160 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
23170 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
23180 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
23190 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61  ement]. ^The X a
231a0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
231b0 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
231c0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
231d0 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51 4c 20   unexpanded SQL 
231e0 74 65 78 74 20 6f 66 20 74 68 65 20 70 72 65 70  text of the prep
231f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
23200 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  r an SQL comment
23210 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
23220 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61 74 69  tes the invocati
23230 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e  on of a trigger.
23240 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20    ^The callback 
23250 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74  can compute.** t
23260 68 65 20 73 61 6d 65 20 74 65 78 74 20 74 68 61  he same text tha
23270 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62 65 65  t would have bee
23280 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
23290 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
232a0 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e  3_trace()].** in
232b0 74 65 72 66 61 63 65 20 62 79 20 75 73 69 6e 67  terface by using
232c0 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20   the X argument 
232d0 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20 77 69  when X begins wi
232e0 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f  th "--" and invo
232f0 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  king.** [sqlite3
23300 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
23310 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  ] otherwise..**.
23320 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
23330 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e  E_PROFILE]] <dt>
23340 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f  SQLITE_TRACE_PRO
23350 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FILE</dt>.** <dd
23360 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
23370 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61  E_PROFILE callba
23380 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70 70 72  ck provides appr
23390 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20 73 61  oximately the sa
233a0 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  me.** informatio
233b0 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64 65 64  n as is provided
233c0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
233d0 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c  _profile()] call
233e0 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  back..** ^The P 
233f0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
23400 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72  inter to the [pr
23410 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23420 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61  ] and the.** X a
23430 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
23440 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67  o a 64-bit integ
23450 65 72 20 77 68 69 63 68 20 69 73 20 74 68 65 20  er which is the 
23460 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20  estimated of.** 
23470 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61  the number of na
23480 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20 74 68  nosecond that th
23490 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
234a0 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
234b0 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45  ..** ^The SQLITE
234c0 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63  _TRACE_PROFILE c
234d0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
234e0 65 64 20 77 68 65 6e 20 74 68 65 20 73 74 61 74  ed when the stat
234f0 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a  ement finishes..
23500 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  **.** [[SQLITE_T
23510 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53  RACE_ROW]] <dt>S
23520 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c  QLITE_TRACE_ROW<
23530 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
23540 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
23550 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
23560 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
23570 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
23580 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65 73 20  ement generates 
23590 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
235a0 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68  result.  .** ^Th
235b0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
235c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
235d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
235e0 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  ment] and the.**
235f0 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75   X argument is u
23600 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  nused..**.** [[S
23610 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
23620 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  E]] <dt>SQLITE_T
23630 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a  RACE_CLOSE</dt>.
23640 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54  ** <dd>^An SQLIT
23650 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 63 61  E_TRACE_CLOSE ca
23660 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
23670 64 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  d when a databas
23680 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
23690 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20  closes..** ^The 
236a0 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
236b0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
236c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
236d0 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  ion] object.** a
236e0 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e  nd the X argumen
236f0 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20  t is unused..** 
23700 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
23710 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54   SQLITE_TRACE_ST
23720 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a 23 64  MT       0x01.#d
23730 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
23740 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20 30 78  CE_PROFILE    0x
23750 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
23760 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20 20 20  E_TRACE_ROW     
23770 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e 65 20     0x04.#define 
23780 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
23790 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a  SE      0x08../*
237a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
237b0 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20  L Trace Hook.** 
237c0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
237d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
237e0 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c  e3_trace_v2(D,M,
237f0 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  X,P) interface r
23800 65 67 69 73 74 65 72 73 20 61 20 74 72 61 63 65  egisters a trace
23810 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
23820 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73 74 20  ction X against 
23830 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
23840 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70  tion] D, using p
23850 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a  roperty mask M.*
23860 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f  * and context po
23870 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20 74 68  inter P.  ^If th
23880 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a  e X callback is.
23890 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68  ** NULL or if th
238a0 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f  e M mask is zero
238b0 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67 20 69  , then tracing i
238c0 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65  s disabled.  The
238d0 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74 20 73  .** M argument s
238e0 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62 69 74  hould be the bit
238f0 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69  wise OR-ed combi
23900 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72  nation of.** zer
23910 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54  o or more [SQLIT
23920 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e  E_TRACE] constan
23930 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  ts..**.** ^Each 
23940 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 73  call to either s
23950 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f  qlite3_trace() o
23960 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  r sqlite3_trace_
23970 76 32 28 29 20 6f 76 65 72 72 69 64 65 73 20 0a  v2() overrides .
23980 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61 6e 79  ** (cancels) any
23990 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20   prior calls to 
239a0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
239b0 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  or sqlite3_trace
239c0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  _v2()..**.** ^Th
239d0 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e X callback is 
239e0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
239f0 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76 65 6e   any of the even
23a00 74 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  ts identified by
23a10 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75   .** mask M occu
23a20 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67 65 72  r.  ^The integer
23a30 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
23a40 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  om the callback 
23a50 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  is currently.** 
23a60 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68 20  ignored, though 
23a70 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67 65 20  this may change 
23a80 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
23a90 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a  es.  Callback.**
23aa0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
23ab0 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a   should return z
23ac0 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20 66 75  ero to ensure fu
23ad0 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69 6c 69  ture compatibili
23ae0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61  ty..**.** ^A tra
23af0 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  ce callback is i
23b00 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f 75 72  nvoked with four
23b10 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c   arguments: call
23b20 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a  back(T,C,P,X)..*
23b30 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e  * ^The T argumen
23b40 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  t is one of the 
23b50 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a  [SQLITE_TRACE].*
23b60 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69  * constants to i
23b70 6e 64 69 63 61 74 65 20 77 68 79 20 74 68 65 20  ndicate why the 
23b80 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e 76  callback was inv
23b90 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20  oked..** ^The C 
23ba0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f  argument is a co
23bb0 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78  py of the contex
23bc0 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68  t pointer..** Th
23bd0 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65  e P and X argume
23be0 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73  nts are pointers
23bf0 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20   whose meanings 
23c00 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a  depend on T..**.
23c10 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74  ** The sqlite3_t
23c20 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65 72 66  race_v2() interf
23c30 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ace is intended 
23c40 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65 20 6c  to replace the l
23c50 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
23c60 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  ces [sqlite3_tra
23c70 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ce()] and [sqlit
23c80 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62  e3_profile()], b
23c90 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20  oth of which.** 
23ca0 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 0a  are deprecated..
23cb0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
23cc0 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  race_v2(.  sqlit
23cd0 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20  e3*,.  unsigned 
23ce0 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43  uMask,.  int(*xC
23cf0 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65  allback)(unsigne
23d00 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f  d,void*,void*,vo
23d10 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43  id*),.  void *pC
23d20 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tx.);../*.** CAP
23d30 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
23d40 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
23d50 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
23d60 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
23d70 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
23d80 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20  andler(D,N,X,P) 
23d90 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
23da0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
23db0 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62   function X to b
23dc0 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  e invoked period
23dd0 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
23de0 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
23df0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
23e00 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
23e10 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73  3_step()] and [s
23e20 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
23e30 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62  ()] for.** datab
23e40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
23e50 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
23e60 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
23e70 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
23e80 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
23e90 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
23ea0 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  query..**.** ^Th
23eb0 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  e parameter P is
23ec0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
23ed0 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
23ee0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a  meter to the .**
23ef0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
23f00 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61  on X.  ^The para
23f10 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61  meter N is the a
23f20 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65  pproximate numbe
23f30 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61  r of .** [virtua
23f40 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75  l machine instru
23f50 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65  ctions] that are
23f60 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65   evaluated betwe
23f70 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a  en successive.**
23f80 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
23f90 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20  the callback X. 
23fa0 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74   ^If N is less t
23fb0 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65  han one then the
23fc0 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e   progress.** han
23fd0 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  dler is disabled
23fe0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20  ..**.** ^Only a 
23ff0 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20  single progress 
24000 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64  handler may be d
24010 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69  efined at one ti
24020 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62  me per.** [datab
24030 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b  ase connection];
24040 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70   setting a new p
24050 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
24060 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f  cancels the.** o
24070 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e  ld one.  ^Settin
24080 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f  g parameter X to
24090 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74   NULL disables t
240a0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
240b0 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f  ler..** ^The pro
240c0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73  gress handler is
240d0 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62   also disabled b
240e0 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61  y setting N to a
240f0 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74   value less.** t
24100 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  han 1..**.** ^If
24110 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
24120 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
24130 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
24140 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
24150 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
24160 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
24170 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
24180 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
24190 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
241a0 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
241b0 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
241c0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
241d0 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
241e0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
241f0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
24200 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
24210 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
24220 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
24230 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
24240 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
24250 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20  3_prepare_v3()] 
24260 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
24270 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
24280 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
24290 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
242a0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
242b0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
242c0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
242d0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
242e0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
242f0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
24300 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
24310 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
24320 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
24330 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
24340 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f  Connection.** CO
24350 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
24360 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e3.**.** ^These 
24370 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
24380 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
24390 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69   file as specifi
243a0 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
243b0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
243c0 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61   ^The filename a
243d0 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
243e0 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
243f0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
24400 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
24410 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
24420 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
24430 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
24440 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
24450 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20  3_open16(). ^(A 
24460 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
24470 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
24480 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
24490 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
244a0 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
244b0 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
244c0 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
244d0 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
244e0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
244f0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
24500 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
24510 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
24520 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
24530 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
24540 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
24550 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
24560 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
24570 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61  )^ ^(If the data
24580 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
24590 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
245a0 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
245b0 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
245c0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
245d0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
245e0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
245f0 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a  urned.)^ ^The.**
24600 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
24610 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
24620 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
24630 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
24640 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
24650 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
24660 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
24670 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f   the error follo
24680 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f  wing a failure o
24690 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  f any.** of the 
246a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
246b0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
246c0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
246d0 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46  ding will be UTF
246e0 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  -8 for databases
246f0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
24700 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
24710 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
24720 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66  _v2().  ^The def
24730 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
24740 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63  r databases.** c
24750 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c  reated using sql
24760 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69  ite3_open16() wi
24770 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20  ll be UTF-16 in 
24780 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
24790 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  order..**.** Whe
247a0 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
247b0 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
247c0 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
247d0 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
247e0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
247f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
24800 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
24810 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
24820 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
24830 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
24840 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
24850 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
24860 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
24870 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24880 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
24890 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
248a0 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
248b0 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
248c0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
248d0 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
248e0 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
248f0 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
24900 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24910 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
24920 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
24930 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
24940 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
24950 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
24960 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
24970 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
24980 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
24990 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
249a0 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
249b0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
249c0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
249d0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
249e0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
249f0 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e  RIVATECACHE], an
24a00 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
24a10 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a  N_URI] flags:)^.
24a20 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
24a30 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
24a40 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
24a50 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
24a60 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
24a70 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
24a80 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
24a90 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
24aa0 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
24ab0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
24ac0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
24ad0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
24ae0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
24af0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
24b00 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
24b10 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
24b20 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
24b30 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
24b40 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
24b50 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
24b60 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
24b70 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
24b80 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
24b90 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
24ba0 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
24bb0 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
24bc0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
24bd0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
24be0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
24bf0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
24c00 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
24c10 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
24c20 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
24c30 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
24c40 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
24c50 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
24c60 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  d if.** it does 
24c70 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
24c80 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
24c90 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
24ca0 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
24cb0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
24cc0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
24cd0 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
24ce0 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
24cf0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
24d00 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
24d10 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
24d20 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
24d30 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
24d40 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79  above optionally
24d50 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f   combined with o
24d60 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ther.** [SQLITE_
24d70 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  OPEN_READONLY | 
24d80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69  SQLITE_OPEN_* bi
24d90 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ts].** then the 
24da0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
24db0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
24dc0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
24dd0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
24de0 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
24df0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24e00 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
24e10 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
24e20 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
24e30 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
24e40 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
24e50 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
24e60 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
24e70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
24e80 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
24e90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
24ea0 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
24eb0 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
24ec0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24ed0 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
24ee0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
24ef0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
24f00 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
24f10 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
24f20 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
24f30 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
24f40 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
24f50 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
24f60 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
24f70 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
24f80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
24f90 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
24fa0 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
24fb0 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
24fc0 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
24fd0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
24fe0 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
24ff0 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
25000 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
25010 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
25020 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
25030 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
25040 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
25050 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
25060 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
25070 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
25080 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
25090 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
250a0 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
250b0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
250c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
250d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
250e0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
250f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
25100 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
25110 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
25120 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
25130 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
25140 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
25150 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
25160 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20  d use.  ^If the 
25170 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
25180 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
25190 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
251a0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
251b0 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
251c0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  sed..**.** ^If t
251d0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
251e0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
251f0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
25200 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
25210 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
25220 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
25230 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73  nnection.  ^This
25240 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
25250 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
25260 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
25270 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
25280 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
25290 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
252a0 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
252b0 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
252c0 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
252d0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
252e0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
252f0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
25300 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
25310 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
25320 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
25330 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
25340 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
25350 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
25360 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
25370 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
25380 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
25390 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
253a0 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
253b0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
253c0 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
253d0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
253e0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
253f0 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
25400 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
25410 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72  eated.  ^This pr
25420 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
25430 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
25440 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
25450 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
25460 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25470 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
25480 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
25490 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f  mes in sqlite3_o
254a0 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20  pen()]] <h3>URI 
254b0 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a  Filenames</h3>.*
254c0 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69  *.** ^If [URI fi
254d0 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65  lename] interpre
254e0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
254f0 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e  d, and the filen
25500 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
25510 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c  begins with "fil
25520 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69  e:", then the fi
25530 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70  lename is interp
25540 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20  reted as a URI. 
25550 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ^URI.** filename
25560 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
25570 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
25580 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
25590 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73  RI] flag is.** s
255a0 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68  et in the fourth
255b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
255c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20  ite3_open_v2(), 
255d0 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  or if it has.** 
255e0 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f  been enabled glo
255f0 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20  bally using the 
25600 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
25610 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20  RI] option with 
25620 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
25630 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64  config()] method
25640 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49   or by the [SQLI
25650 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70  TE_USE_URI] comp
25660 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
25670 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65  .** As of SQLite
25680 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
25690 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  URI filename int
256a0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74  erpretation is t
256b0 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20  urned off.** by 
256c0 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74  default, but fut
256d0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
256e0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61  SQLite might ena
256f0 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  ble URI filename
25700 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69  .** interpretati
25710 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
25720 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61  See "[URI filena
25730 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69  mes]" for additi
25740 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
25750 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66  ion..**.** URI f
25760 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72  ilenames are par
25770 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  sed according to
25780 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74   RFC 3986. ^If t
25790 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
257a0 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c  an.** authority,
257b0 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65   then it must be
257c0 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79   either an empty
257d0 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73   string or the s
257e0 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c  tring .** "local
257f0 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61  host". ^If the a
25800 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20  uthority is not 
25810 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
25820 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20  or "localhost", 
25830 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20  an .** error is 
25840 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
25850 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61  caller. ^The fra
25860 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  gment component 
25870 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a  of a URI, if .**
25880 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e   present, is ign
25890 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ored..**.** ^SQL
258a0 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74  ite uses the pat
258b0 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74  h component of t
258c0 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61  he URI as the na
258d0 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66  me of the disk f
258e0 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e  ile.** which con
258f0 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61  tains the databa
25900 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  se. ^If the path
25910 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27   begins with a '
25920 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a  /' character, .*
25930 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  * then it is int
25940 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61  erpreted as an a
25950 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49  bsolute path. ^I
25960 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20  f the path does 
25970 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69  not begin .** wi
25980 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e  th a '/' (meanin
25990 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  g that the autho
259a0 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
259b0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
259c0 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68   URI).** then th
259d0 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70  e path is interp
259e0 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74  reted as a relat
259f0 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28  ive path. .** ^(
25a00 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20  On windows, the 
25a10 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  first component 
25a20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  of an absolute p
25a30 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69  ath .** is a dri
25a40 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  ve specification
25a50 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a   (e.g. "C:").)^.
25a60 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49  **.** [[core URI
25a70 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
25a80 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79  s]].** The query
25a90 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
25aa0 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  URI may contain 
25ab0 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
25ac0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a  are interpreted.
25ad0 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c  ** either by SQL
25ae0 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62  ite itself, or b
25af0 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f  y a [VFS | custo
25b00 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  m VFS implementa
25b10 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65  tion]..** SQLite
25b20 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69   and its built-i
25b30 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70  n [VFSes] interp
25b40 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ret the.** follo
25b50 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d  wing query param
25b60 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
25b70 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
25b80 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
25b90 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
25ba0 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
25bb0 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
25bc0 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
25bd0 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
25be0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
25bf0 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
25c00 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
25c10 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
25c20 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
25c30 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
25c40 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
25c50 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
25c60 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
25c70 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
25c80 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
25c90 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
25ca0 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
25cb0 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
25cc0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
25cd0 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
25ce0 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
25cf0 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
25d00 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
25d10 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
25d20 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
25d30 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
25d40 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
25d50 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
25d60 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
25d70 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
25d80 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
25d90 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
25da0 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
25db0 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
25dc0 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
25dd0 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77  "rw",.**     "rw
25de0 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e  c", or "memory".
25df0 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73   Attempting to s
25e00 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68  et it to any oth
25e10 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20  er value is.**  
25e20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a     an error)^. .
25e30 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
25e40 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
25e50 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
25e60 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
25e70 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
25e80 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
25e90 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
25ea0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
25eb0 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
25ec0 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
25ed0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
25ee0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
25ef0 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  (). ^If the mode
25f00 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
25f10 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20  o .**     "rw", 
25f20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
25f30 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
25f40 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20  read-write (but 
25f50 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20  not create) .** 
25f60 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69      access, as i
25f70 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  f SQLITE_OPEN_RE
25f80 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74  ADWRITE (but not
25f90 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
25fa0 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20  ATE) had .**    
25fb0 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75   been set. ^Valu
25fc0 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76  e "rwc" is equiv
25fd0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
25fe0 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51   both .**     SQ
25ff0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
26000 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f  ITE and SQLITE_O
26010 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66  PEN_CREATE.  ^If
26020 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
26030 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74   is.**     set t
26040 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20  o "memory" then 
26050 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72  a pure [in-memor
26060 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74  y database] that
26070 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20   never reads.** 
26080 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72      or writes fr
26090 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e  om disk is used.
260a0 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72   ^It is an error
260b0 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
260c0 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74  lue for.**     t
260d0 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
260e0 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72  r that is less r
260f0 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20  estrictive than 
26100 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62  that specified b
26110 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61  y.**     the fla
26120 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65  gs passed in the
26130 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
26140 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
26150 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
26160 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
26170 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
26180 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
26190 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
261a0 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
261b0 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
261c0 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
261d0 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
261e0 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
261f0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
26200 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
26210 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
26220 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
26230 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
26240 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
26250 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
26260 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
26270 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
26280 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
26290 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
262a0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
262b0 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
262c0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
262d0 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
262e0 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
262f0 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
26300 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
26310 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
26320 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
26330 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65   any behavior re
26340 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
26350 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
26360 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
26370 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
26380 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
26390 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  ag..**.**  <li> 
263a0 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68  <b>psow</b>: ^Th
263b0 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72  e psow parameter
263c0 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68   indicates wheth
263d0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a  er or not the.**
263e0 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20       [powersafe 
263f0 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65  overwrite] prope
26400 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73  rty does or does
26410 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68   not apply to th
26420 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65  e.**     storage
26430 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20   media on which 
26440 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
26450 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a  e resides..**.**
26460 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b    <li> <b>nolock
26470 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63  </b>: ^The noloc
26480 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  k parameter is a
26490 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70   boolean query p
264a0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
264b0 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73  which if set dis
264c0 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69  ables file locki
264d0 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a  ng in rollback j
264e0 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54  ournal modes.  T
264f0 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73  his.**     is us
26500 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69  eful for accessi
26510 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e  ng a database on
26520 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68   a filesystem th
26530 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  at does not.**  
26540 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69     support locki
26550 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44  ng.  Caution:  D
26560 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
26570 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  on might result 
26580 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72  if two.**     or
26590 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20   more processes 
265a0 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d  write to the sam
265b0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  e database and a
265c0 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a  ny one of those.
265d0 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73  **     processes
265e0 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a   uses nolock=1..
265f0 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69  **.**  <li> <b>i
26600 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54  mmutable</b>: ^T
26610 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72  he immutable par
26620 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
26630 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20  ean query.**    
26640 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
26650 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
26660 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
26670 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a   is stored on.**
26680 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d       read-only m
26690 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d  edia.  ^When imm
266a0 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53  utable is set, S
266b0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
266c0 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61  at the.**     da
266d0 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e  tabase file cann
266e0 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65  ot be changed, e
266f0 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73  ven by a process
26700 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20   with higher.** 
26710 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61      privilege, a
26720 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61  nd so the databa
26730 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61  se is opened rea
26740 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c  d-only and all l
26750 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e  ocking.**     an
26760 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69  d change detecti
26770 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  on is disabled. 
26780 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e   Caution: Settin
26790 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a  g the immutable.
267a0 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20  **     property 
267b0 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  on a database fi
267c0 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20  le that does in 
267d0 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20  fact change can 
267e0 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e  result.**     in
267f0 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79   incorrect query
26800 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20   results and/or 
26810 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
26820 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20   errors..**     
26830 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
26840 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
26850 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a  E]..**       .**
26860 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70   </ul>.**.** ^Sp
26870 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
26880 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e  own parameter in
26890 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   the query compo
268a0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73  nent of a URI is
268b0 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72   not an.** error
268c0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
268d0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
268e0 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64  ht understand ad
268f0 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a  ditional query.*
26900 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53  * parameters.  S
26910 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d  ee "[query param
26920 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69  eters with speci
26930 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51  al meaning to SQ
26940 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64  Lite]" for.** ad
26950 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
26960 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  tion..**.** [[UR
26970 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
26980 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69  les]] <h3>URI fi
26990 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c  lename examples<
269a0 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c  /h3>.**.** <tabl
269b0 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69  e border="1" ali
269c0 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61  gn=center cellpa
269d0 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e  dding=5>.** <tr>
269e0 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d  <th> URI filenam
269f0 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a  es <th> Results.
26a00 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
26a10 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  :data.db <td> .*
26a20 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
26a30 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
26a40 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
26a50 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  t directory..** 
26a60 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
26a70 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
26a80 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <br>.**         
26a90 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72   file:///home/fr
26aa0 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
26ab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
26ac0 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f  e://localhost/ho
26ad0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
26ae0 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  <br> <td> .**   
26af0 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
26b00 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f  database file "/
26b10 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26b20 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  b"..** <tr><td> 
26b30 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f  file://darkstar/
26b40 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26b50 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
26b60 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64      An error. "d
26b70 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20  arkstar" is not 
26b80 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74  a recognized aut
26b90 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  hority..** <tr><
26ba0 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d  td style="white-
26bb0 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a  space:nowrap"> .
26bc0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
26bd0 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73  :///C:/Documents
26be0 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67  %20and%20Setting
26bf0 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64  s/fred/Desktop/d
26c00 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74  ata.db.**     <t
26c10 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a  d> Windows only:
26c20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
26c30 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64  data.db" on fred
26c40 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72  's desktop on dr
26c50 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
26c60 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  C:. Note that th
26c70 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69  e %20 escaping i
26c80 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69  n this example i
26c90 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a  s not strictly .
26ca0 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65  **          nece
26cb0 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68  ssary - space ch
26cc0 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20  aracters can be 
26cd0 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a  used literally.*
26ce0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52  *          in UR
26cf0 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20  I filenames..** 
26d00 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
26d10 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61  ta.db?mode=ro&ca
26d20 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e  che=private <td>
26d30 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
26d40 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  en file "data.db
26d50 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
26d60 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72   directory for r
26d70 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e  ead-only access.
26d80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67  .**          Reg
26d90 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
26da0 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
26db0 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65  -cache mode is e
26dc0 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20  nabled by.**    
26dd0 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75        default, u
26de0 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63  se a private cac
26df0 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  he..** <tr><td> 
26e00 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
26e10 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78  data.db?vfs=unix
26e20 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a  -dotfile <td>.**
26e30 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
26e40 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
26e50 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
26e60 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
26e70 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20  nix-dotfile".** 
26e80 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73           that us
26e90 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20  es dot-files in 
26ea0 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61  place of posix a
26eb0 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e  dvisory locking.
26ec0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
26ed0 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
26ee0 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
26ef0 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
26f00 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
26f10 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
26f20 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
26f30 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
26f40 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
26f50 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
26f60 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
26f70 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
26f80 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
26f90 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
26fa0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
26fb0 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
26fc0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
26fd0 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
26fe0 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
26ff0 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
27000 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
27010 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
27020 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
27030 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
27040 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
27050 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
27060 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
27070 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
27080 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
27090 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
270a0 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
270b0 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
270c0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
270d0 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
270e0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
270f0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
27100 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
27110 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
27120 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
27130 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
27140 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
27150 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
27160 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
27170 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
27180 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
27190 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
271a0 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
271b0 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
271c0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
271d0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
271e0 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
271f0 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
27200 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
27210 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
27220 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
27230 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
27240 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
27250 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
27260 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
27270 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
27280 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
27290 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
272a0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
272b0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
272c0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
272d0 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
272e0 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
272f0 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
27300 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
27310 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
27320 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
27330 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
27340 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
27350 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
27360 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
27370 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
27380 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
27390 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
273a0 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
273b0 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e  directory].*/.in
273c0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
273d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
273e0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
273f0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
27400 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
27410 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
27420 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
27430 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
27440 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
27450 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
27460 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
27470 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
27480 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
27490 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
274a0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
274b0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
274c0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
274d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
274e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
274f0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
27500 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
27510 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
27520 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
27530 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
27540 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
27550 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
27560 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
27570 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
27580 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
27590 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
275a0 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
275b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
275c0 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65  EF: Obtain Value
275d0 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65  s For URI Parame
275e0 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ters.**.** These
275f0 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75   are utility rou
27600 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f  tines, useful to
27610 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
27620 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
27630 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20  .** to see if a 
27640 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
27650 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e  s a URI that con
27660 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69  tained a specifi
27670 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61  c query .** para
27680 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f  meter, and if so
27690 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c   obtains the val
276a0 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79  ue of that query
276b0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
276c0 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61  * If F is the da
276d0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
276e0 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
276f0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20  nto the xOpen() 
27700 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20  method of .** a 
27710 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
27720 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67  on when the flag
27730 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  s parameter to x
27740 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f  Open() has one o
27750 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  r .** more of th
27760 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
27770 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  RI] or [SQLITE_O
27780 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74  PEN_MAIN_DB] bit
27790 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69  s set and.** P i
277a0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
277b0 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
277c0 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  r, then.** sqlit
277d0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
277e0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68  (F,P) returns th
277f0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50  e value of the P
27800 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
27810 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20   it exists or a 
27820 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
27830 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  P does not appea
27840 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79  r as a .** query
27850 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e   parameter on F.
27860 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72    If P is a quer
27870 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46  y parameter of F
27880 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69  .** has no expli
27890 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  cit value, then 
278a0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
278b0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
278c0 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ns.** a pointer 
278d0 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
278e0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ng..**.** The sq
278f0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
27900 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
27910 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20   assumes that P 
27920 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20  is a boolean.** 
27930 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
27940 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f  turns true (1) o
27950 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f  r false (0) acco
27960 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c  rding to the val
27970 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65  ue.** of P.  The
27980 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
27990 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
279a0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ine returns true
279b0 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76   (1) if the.** v
279c0 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61  alue of query pa
279d0 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
279e0 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65   of "yes", "true
279f0 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e  ", or "on" in an
27a00 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20  y.** case or if 
27a10 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
27a20 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
27a30 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a   number.  The .*
27a40 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
27a50 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
27a60 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61  tines returns fa
27a70 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76  lse (0) if the v
27a80 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79  alue of.** query
27a90 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
27aa0 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61  one of "no", "fa
27ab0 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69  lse", or "off" i
27ac0 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a  n any case or.**
27ad0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
27ae0 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65  gins with a nume
27af0 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20  ric zero.  If P 
27b00 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a  is not a query.*
27b10 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  * parameter on F
27b20 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
27b30 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f   of P is does no
27b40 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74  t match any of t
27b50 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65  he.** above, the
27b60 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  n sqlite3_uri_bo
27b70 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
27b80 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a  urns (B!=0)..**.
27b90 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
27ba0 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20  ri_int64(F,P,D) 
27bb0 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73  routine converts
27bc0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
27bd0 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74  into a.** 64-bit
27be0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
27bf0 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74  and returns that
27c00 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69   integer, or D i
27c10 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  f P does not.** 
27c20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76  exist.  If the v
27c30 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d  alue of P is som
27c40 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
27c50 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  n an integer, th
27c60 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65  en.** zero is re
27c70 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49  turned..** .** I
27c80 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f F is a NULL po
27c90 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69  inter, then sqli
27ca0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
27cb0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e  r(F,P) returns N
27cc0 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  ULL and.** sqlit
27cd0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
27ce0 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e  ,P,B) returns B.
27cf0 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20    If F is not a 
27d00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
27d10 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74  .** is not a dat
27d20 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e  abase file pathn
27d30 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ame pointer that
27d40 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69   SQLite passed i
27d50 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a  nto the xOpen.**
27d60 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
27d70 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
27d80 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
27d90 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
27da0 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65  probably.** unde
27db0 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73  sirable..*/.cons
27dc0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
27dd0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
27de0 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
27df0 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
27e00 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71  *zParam);.int sq
27e10 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
27e20 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
27e30 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
27e40 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
27e50 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f  fault);.sqlite3_
27e60 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72  int64 sqlite3_ur
27e70 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
27e80 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
27e90 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
27ea0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
27eb0 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
27ec0 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20  And Messages.** 
27ed0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
27ee0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
27ef0 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65  st recent sqlite
27f00 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73  3_* API call ass
27f10 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a  ociated with .**
27f20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
27f30 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c  ction] D failed,
27f40 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
27f50 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74  3_errcode(D) int
27f60 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e  erface.** return
27f70 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
27f80 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b  esult code] or [
27f90 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
27fa0 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a  code] for that.*
27fb0 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49  * API call..** I
27fc0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
27fd0 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73  t API call was s
27fe0 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68  uccessful,.** th
27ff0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
28000 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
28010 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
28020 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  defined..** ^The
28030 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
28040 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  d_errcode().** i
28050 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
28060 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74  same except that
28070 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
28080 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65  ns the .** [exte
28090 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
280a0 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65  ] even when exte
280b0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
280c0 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
280d0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
280e0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
280f0 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
28100 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
28110 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
28120 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
28130 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
28140 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
28150 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
28160 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d  tively..** ^(Mem
28170 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
28180 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
28190 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
281a0 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
281b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
281c0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
281d0 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
281e0 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
281f0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
28200 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
28210 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
28220 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
28230 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
28240 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
28250 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
28260 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a  e functions.)^.*
28270 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
28280 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72  3_errstr() inter
28290 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
282a0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
282b0 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64  e text.** that d
282c0 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65  escribes the [re
282d0 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55  sult code], as U
282e0 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  TF-8..** ^(Memor
282f0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
28300 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
28310 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
28320 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20  ternally.** and 
28330 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65  must not be free
28340 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
28350 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68  tion)^..**.** Wh
28360 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
28370 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
28380 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
28390 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
283a0 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
283b0 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
283c0 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
283d0 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
283e0 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
283f0 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
28400 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
28410 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
28420 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
28430 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
28440 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
28450 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
28460 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
28470 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
28480 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
28490 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
284a0 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
284b0 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
284c0 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
284d0 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
284e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
284f0 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
28500 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
28510 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
28520 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
28530 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
28540 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
28550 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
28560 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
28570 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
28580 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
28590 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
285a0 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
285b0 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
285c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
285d0 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
285e0 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
285f0 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
28600 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
28610 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
28620 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
28630 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
28640 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
28650 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
28660 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
28670 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
28680 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
28690 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
286a0 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
286b0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
286c0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
286d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
286e0 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
286f0 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
28700 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
28710 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  16(sqlite3*);.co
28720 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
28730 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a  3_errstr(int);..
28740 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28750 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
28760 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
28770 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
28780 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
28790 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
287a0 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
287b0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
287c0 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
287d0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
287e0 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73  ment that.** has
287f0 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69   been compiled i
28800 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20  nto binary form 
28810 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f 20  and is ready to 
28820 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a  be evaluated..**
28830 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63  .** Think of eac
28840 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
28850 61 73 20 61 20 73 65 70 61 72 61 74 65 20 63 6f  as a separate co
28860 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20  mputer program. 
28870 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   The.** original
28880 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75   SQL text is sou
28890 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65  rce code.  A pre
288a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
288b0 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68  object .** is th
288c0 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63  e compiled objec
288d0 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c  t code.  All SQL
288e0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
288f0 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65  ed into a.** pre
28900 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
28910 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65  before it can be
28920 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   run..**.** The 
28930 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20  life-cycle of a 
28940 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28950 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c  nt object usuall
28960 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73  y goes like this
28970 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
28980 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
28990 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
289a0 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  nt object using 
289b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
289c0 5f 76 33 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20  _v3()]..** <li> 
289d0 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
289e0 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
289f0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
28a00 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
28a10 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
28a20 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
28a30 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
28a40 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
28a50 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
28a60 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
28a70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28a80 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
28a90 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
28aa0 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
28ab0 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
28ac0 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
28ad0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
28ae0 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
28af0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
28b00 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
28b10 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64  * </ol>.*/.typed
28b20 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
28b30 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
28b40 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
28b50 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
28b60 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  imits.** METHOD:
28b70 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
28b80 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
28b90 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
28ba0 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
28bb0 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
28bc0 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
28bd0 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
28be0 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
28bf0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
28c00 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
28c10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
28c20 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
28c30 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
28c40 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
28c50 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
28c60 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
28c70 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
28c80 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
28c90 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
28ca0 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
28cb0 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
28cc0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
28cd0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
28ce0 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
28cf0 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
28d00 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
28d10 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
28d20 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
28d30 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
28d40 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
28d50 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
28d60 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
28d70 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
28d80 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
28d90 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
28da0 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
28db0 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
28dc0 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
28dd0 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
28de0 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
28df0 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
28e00 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
28e10 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
28e20 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
28e30 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
28e40 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
28e50 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
28e60 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
28e70 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
28e80 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
28e90 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
28ea0 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
28eb0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
28ec0 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
28ed0 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
28ee0 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
28ef0 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
28f00 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
28f10 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
28f20 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
28f30 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
28f40 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
28f50 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
28f60 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
28f70 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
28f80 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
28f90 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
28fa0 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
28fb0 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
28fc0 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
28fd0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
28fe0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
28ff0 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
29000 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
29010 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
29020 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
29030 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
29040 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
29050 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
29060 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
29070 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
29080 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
29090 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
290a0 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
290b0 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
290c0 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
290d0 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
290e0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
290f0 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
29100 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
29110 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
29120 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
29130 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
29140 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
29150 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
29160 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
29170 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
29180 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
29190 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
291a0 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
291b0 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
291c0 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
291d0 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
291e0 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
291f0 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
29200 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
29210 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
29220 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
29230 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
29240 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
29250 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
29260 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
29270 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
29280 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
29290 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
292a0 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
292b0 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
292c0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
292d0 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
292e0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
292f0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
29300 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
29310 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
29320 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
29330 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
29340 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
29350 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
29360 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
29370 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
29380 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
29390 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
293a0 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
293b0 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
293c0 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
293d0 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
293e0 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
293f0 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
29400 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
29410 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
29420 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
29430 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
29440 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
29450 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
29460 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
29470 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
29480 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
29490 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
294a0 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
294b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
294c0 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
294d0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
294e0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
294f0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
29500 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
29510 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
29520 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
29530 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
29540 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
29550 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
29560 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
29570 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
29580 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
29590 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
295a0 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
295b0 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
295c0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
295d0 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
295e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
295f0 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
29600 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
29610 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
29620 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
29630 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
29640 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
29650 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
29660 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
29670 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
29680 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
29690 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
296a0 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
296b0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
296c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
296d0 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
296e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
296f0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
29700 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
29710 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
29720 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
29730 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
29740 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29750 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
29760 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
29770 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
29780 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
29790 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
297a0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
297b0 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
297c0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
297d0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
297e0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
297f0 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
29800 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
29810 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
29820 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
29830 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
29840 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
29850 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
29860 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
29870 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
29880 6d 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c 69 74  ment.  If [sqlit
29890 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
298a0 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75 69 76   or.** the equiv
298b0 61 6c 65 6e 74 20 74 72 69 65 73 20 74 6f 20 61  alent tries to a
298c0 6c 6c 6f 63 61 74 65 20 73 70 61 63 65 20 66 6f  llocate space fo
298d0 72 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 69 73  r more than this
298e0 20 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a   many opcodes.**
298f0 20 69 6e 20 61 20 73 69 6e 67 6c 65 20 70 72 65   in a single pre
29900 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c  pared statement,
29910 20 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d   an SQLITE_NOMEM
29920 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
29930 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
29940 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29950 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e  FUNCTION_ARG]] ^
29960 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
29970 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
29980 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29990 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
299a0 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
299b0 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
299c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
299d0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d  LIMIT_ATTACHED]]
299e0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
299f0 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
29a00 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29a10 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
29a20 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
29a30 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
29a40 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
29a50 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
29a60 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a  ATTERN_LENGTH]].
29a70 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
29a80 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
29a90 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
29aa0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29ab0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
29ac0 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
29ad0 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
29ae0 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
29af0 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
29b00 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29b10 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
29b20 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ER]].** ^(<dt>SQ
29b30 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
29b40 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
29b50 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29b60 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20  um index number 
29b70 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65  of any [paramete
29b80 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  r] in an SQL sta
29b90 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  tement.)^.**.** 
29ba0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  [[SQLITE_LIMIT_T
29bb0 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e  RIGGER_DEPTH]] ^
29bc0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
29bd0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
29be0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29bf0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
29c00 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
29c10 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a  riggers.</dd>)^.
29c20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29c30 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
29c40 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ADS]] ^(<dt>SQLI
29c50 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
29c60 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20  THREADS</dt>.** 
29c70 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29c80 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69  number of auxili
29c90 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61  ary worker threa
29ca0 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65  ds that a single
29cb0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
29cc0 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61  atement] may sta
29cd0 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rt.</dd>)^.** </
29ce0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
29cf0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
29d00 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
29d10 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
29d20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
29d30 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
29d40 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
29d50 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
29d60 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
29d70 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
29d80 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
29d90 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
29da0 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
29db0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29dc0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
29dd0 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
29de0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29df0 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
29e00 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
29e10 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29e20 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
29e30 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
29e40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29e50 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
29e60 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
29e70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29e80 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
29e90 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
29ea0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29eb0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
29ec0 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
29ed0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29ee0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
29ef0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
29f00 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
29f10 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
29f20 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20  READS           
29f30 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  11../*.** CAPI3R
29f40 45 46 3a 20 50 72 65 70 61 72 65 20 46 6c 61 67  EF: Prepare Flag
29f50 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 0a 2a  s.** KEYWORDS:.*
29f60 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
29f70 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
29f80 6f 75 73 20 66 6c 61 67 73 20 74 68 61 74 20 63  ous flags that c
29f90 61 6e 20 62 65 20 70 61 73 73 65 64 20 69 6e 74  an be passed int
29fa0 6f 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  o.** the [sqlite
29fb0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20  3_prepare_v3()] 
29fc0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
29fd0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
29fe0 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53  E_PREPARE_PERSIS
29ff0 54 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  TENT]] ^(<dt>SQL
2a000 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53  ITE_PREPARE_PERS
2a010 49 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  ISTENT</dt>.** <
2a020 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50 52  dd>The SQLITE_PR
2a030 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54  EPARE_PERSISTENT
2a040 20 66 6c 61 67 20 63 61 75 73 65 73 20 5b 73 71   flag causes [sq
2a050 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2a060 28 29 5d 0a 2a 2a 20 74 6f 20 6f 70 74 69 6d 69  ()].** to optimi
2a070 7a 65 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ze the resulting
2a080 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2a090 65 6e 74 20 74 6f 20 62 65 20 72 65 74 61 69 6e  ent to be retain
2a0a0 65 64 20 66 6f 72 20 61 20 0a 2a 2a 20 72 65 6c  ed for a .** rel
2a0b0 61 74 69 76 65 6c 79 20 6c 6f 6e 67 20 61 6d 6f  atively long amo
2a0c0 75 6e 74 20 6f 66 20 74 69 6d 65 2e 29 5e 20 20  unt of time.)^  
2a0d0 5e 57 69 74 68 6f 75 74 20 74 68 69 73 20 66 6c  ^Without this fl
2a0e0 61 67 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ag,.** [sqlite3_
2a0f0 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 61 73  prepare_v3()] as
2a100 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 70  sumes that the p
2a110 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a120 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 0a 2a  t will be used.*
2a130 2a 20 6a 75 73 74 20 6f 6e 63 65 20 6f 72 20 61  * just once or a
2a140 74 20 6d 6f 73 74 20 61 20 66 65 77 20 74 69 6d  t most a few tim
2a150 65 73 20 61 6e 64 20 74 68 65 6e 20 64 65 73 74  es and then dest
2a160 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  royed using.** [
2a170 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2a180 28 29 5d 20 72 65 6c 61 74 69 76 65 6c 79 20 73  ()] relatively s
2a190 6f 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  oon..** </dl>.*/
2a1a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a1b0 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2a1c0 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
2a1d0 30 78 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0x01../*.** CAPI
2a1e0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
2a1f0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2a200 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
2a210 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
2a220 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  piler}.** METHOD
2a230 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e  : sqlite3.** CON
2a240 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2a250 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20  3_stmt.**.** To 
2a260 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
2a270 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
2a280 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
2a290 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
2a2a0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
2a2b0 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
2a2c0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
2a2d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2a2e0 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
2a2f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a300 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
2a310 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
2a320 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2a330 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
2a340 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
2a350 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
2a360 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
2a370 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
2a380 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
2a390 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
2a3a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
2a3b0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
2a3c0 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
2a3d0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
2a3e0 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
2a3f0 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
2a400 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
2a410 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
2a420 72 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72  re(), sqlite3_pr
2a430 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a 20 61  epare_v2(),.** a
2a440 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2a450 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v3().** inter
2a460 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
2a470 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2a480 70 61 72 65 31 36 28 29 2c 20 73 71 6c 69 74 65  pare16(), sqlite
2a490 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2a4a0 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ,.** and sqlite3
2a4b0 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 20  _prepare16_v3() 
2a4c0 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
2a4d0 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
2a4e0 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61  argument is nega
2a4f0 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20  tive, then zSql 
2a500 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
2a510 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
2a520 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
2a530 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69 76  nByte is positiv
2a540 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
2a550 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
2a560 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
2a570 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20  Sql.  ^If nByte 
2a580 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f  is zero, then no
2a590 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2a5a0 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61  tement is genera
2a5b0 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ted..** If the c
2a5c0 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74  aller knows that
2a5d0 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
2a5e0 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
2a5f0 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  inated, then.** 
2a600 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
2a610 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
2a620 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e  antage to passin
2a630 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
2a640 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
2a650 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2a660 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
2a670 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
2a680 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
2a690 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  nul-terminator..
2a6a0 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
2a6b0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
2a6c0 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
2a6d0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
2a6e0 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
2a6f0 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
2a700 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
2a710 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
2a720 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
2a730 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
2a740 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
2a750 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
2a760 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
2a770 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
2a780 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
2a790 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
2a7a0 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
2a7b0 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
2a7c0 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
2a7d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2a7e0 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
2a7f0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
2a800 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
2a810 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
2a820 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
2a830 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
2a840 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
2a850 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
2a860 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
2a870 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
2a880 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
2a890 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
2a8a0 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
2a8b0 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
2a8c0 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
2a8d0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
2a8e0 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
2a8f0 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
2a900 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
2a910 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2a920 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
2a930 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
2a940 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
2a950 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
2a960 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
2a970 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2a980 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
2a990 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
2a9a0 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
2a9b0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
2a9c0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
2a9d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
2a9e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2a9f0 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70  (), sqlite3_prep
2aa00 61 72 65 5f 76 33 28 29 2c 20 73 71 6c 69 74 65  are_v3(), sqlite
2aa10 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2aa20 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ,.** and sqlite3
2aa30 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 20  _prepare16_v3() 
2aa40 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
2aa50 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
2aa60 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
2aa70 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20 69 6e  .** The older in
2aa80 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
2aa90 61 69 6e 65 64 20 28 73 71 6c 69 74 65 33 5f 70  ained (sqlite3_p
2aaa0 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
2aab0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2aac0 29 0a 2a 2a 20 61 72 65 20 72 65 74 61 69 6e 65  ).** are retaine
2aad0 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
2aae0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
2aaf0 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
2ab00 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
2ab10 5e 49 6e 20 74 68 65 20 22 76 58 22 20 69 6e 74  ^In the "vX" int
2ab20 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
2ab30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
2ab40 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
2ab50 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
2ab60 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
2ab70 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
2ab80 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
2ab90 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
2aba0 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
2abb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
2abc0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
2abd0 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
2abe0 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
2abf0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
2ac00 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
2ac10 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
2ac20 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
2ac30 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
2ac40 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
2ac50 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
2ac60 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
2ac70 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
2ac80 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
2ac90 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
2aca0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2acb0 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
2acc0 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b  in. As many as [
2acd0 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d  SQLITE_MAX_SCHEM
2ace0 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72  A_RETRY].** retr
2acf0 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62  ies will occur b
2ad00 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74  efore sqlite3_st
2ad10 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e  ep() gives up an
2ad20 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  d returns an err
2ad30 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  or..** </li>.**.
2ad40 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
2ad50 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
2ad60 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
2ad70 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
2ad80 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
2ad90 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
2ada0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
2adb0 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
2adc0 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
2add0 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
2ade0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2adf0 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
2ae00 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
2ae10 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
2ae20 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
2ae30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2ae40 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
2ae50 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
2ae60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2ae70 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
2ae80 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
2ae90 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
2aea0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
2aeb0 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
2aec0 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
2aed0 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
2aee0 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
2aef0 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
2af00 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
2af10 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
2af20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
2af30 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
2af40 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
2af50 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
2af60 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
2af70 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
2af80 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
2af90 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
2afa0 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
2afb0 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
2afc0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
2afd0 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
2afe0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
2aff0 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
2b000 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
2b010 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
2b020 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
2b030 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
2b040 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
2b050 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
2b060 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
2b070 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
2b080 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
2b090 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
2b0a0 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
2b0b0 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
2b0c0 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
2b0d0 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
2b0e0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
2b0f0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2b100 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
2b110 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
2b120 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
2b130 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
2b140 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
2b150 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
2b160 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
2b170 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
2b180 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
2b190 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
2b1a0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
2b1b0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2b1c0 70 3e 5e 73 71 6c 69 74 65 33 5f 70 72 65 70 61  p>^sqlite3_prepa
2b1d0 72 65 5f 76 33 28 29 20 64 69 66 66 65 72 73 20  re_v3() differs 
2b1e0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 70 72 65  from sqlite3_pre
2b1f0 70 61 72 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69  pare_v2() only i
2b200 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20  n having.** the 
2b210 65 78 74 72 61 20 70 72 65 70 46 6c 61 67 73 20  extra prepFlags 
2b220 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68  parameter, which
2b230 20 69 73 20 61 20 62 69 74 20 61 72 72 61 79 20   is a bit array 
2b240 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20 7a 65  consisting of ze
2b250 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66  ro or.** more of
2b260 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 50 52 45   the [SQLITE_PRE
2b270 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 7c  PARE_PERSISTENT|
2b280 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 2a  SQLITE_PREPARE_*
2b290 5d 20 66 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a  ] flags.  ^The.*
2b2a0 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
2b2b0 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
2b2c0 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 74   works exactly t
2b2d0 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71  he same as.** sq
2b2e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2b2f0 28 29 20 77 69 74 68 20 61 20 7a 65 72 6f 20 70  () with a zero p
2b300 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74  repFlags paramet
2b310 65 72 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  er..** </ol>.*/.
2b320 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2b330 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
2b340 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2b350 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2b360 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2b370 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2b380 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2b390 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2b3a0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2b3b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2b3c0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2b3d0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2b3e0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2b3f0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2b400 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2b410 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2b420 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
2b430 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2b440 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2b450 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2b460 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2b470 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
2b480 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2b490 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2b4a0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2b4b0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2b4c0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2b4d0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2b4e0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2b4f0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2b500 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2b510 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2b520 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2b530 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2b540 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2b550 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2b560 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
2b570 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2b580 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2b590 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2b5a0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
2b5b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2b5c0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2b5d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2b5e0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2b5f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2b600 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2b610 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2b620 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2b630 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2b640 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2b650 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2b660 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2b670 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72   unsigned int pr
2b680 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f  epFlags, /* Zero
2b690 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f   or more SQLITE_
2b6a0 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a  PREPARE_ flags *
2b6b0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2b6c0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2b6d0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2b6e0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2b6f0 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2b700 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2b710 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2b720 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2b730 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2b740 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
2b750 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2b760 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2b770 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2b780 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
2b790 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2b7a0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
2b7b0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2b7c0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2b7d0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2b7e0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2b7f0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2b800 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2b810 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2b820 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2b830 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
2b840 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2b850 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2b860 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2b870 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
2b880 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2b890 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2b8a0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2b8b0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2b8c0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2b8d0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2b8e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2b8f0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
2b900 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2b910 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2b920 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2b930 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2b940 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2b950 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2b960 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2b970 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2b980 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2b990 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2b9a0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2b9b0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2b9c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
2b9d0 70 61 72 65 31 36 5f 76 33 28 0a 20 20 73 71 6c  pare16_v3(.  sql
2b9e0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2b9f0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2ba00 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2ba10 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
2ba20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2ba30 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
2ba40 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2ba50 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2ba60 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2ba70 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2ba80 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69  bytes. */.  unsi
2ba90 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46 61 6c  gned int prepFal
2baa0 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d  gs, /* Zero or m
2bab0 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  ore SQLITE_PREPA
2bac0 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73  RE_ flags */.  s
2bad0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2bae0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2baf0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2bb00 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2bb10 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2bb20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2bb30 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2bb40 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
2bb50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2bb60 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
2bb70 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44  nt SQL.** METHOD
2bb80 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2bb90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2bba0 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61  3_sql(P) interfa
2bbb0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2bbc0 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79 20 6f  nter to a copy o
2bbd0 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53  f the UTF-8.** S
2bbe0 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
2bbf0 63 72 65 61 74 65 20 5b 70 72 65 70 61 72 65 64  create [prepared
2bc00 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 69 66   statement] P if
2bc10 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 74 65   P was.** create
2bc20 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  d by [sqlite3_pr
2bc30 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
2bc40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2bc50 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2bc60 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2bc70 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  , or [sqlite3_pr
2bc80 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a  epare16_v3()]..*
2bc90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
2bca0 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69  xpanded_sql(P) i
2bcb0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2bcc0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2bcd0 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
2bce0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53  containing the S
2bcf0 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70 61  QL text of prepa
2bd00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
2bd10 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70  with.** [bound p
2bd20 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e  arameters] expan
2bd30 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
2bd40 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70   example, if a p
2bd50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2bd60 74 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69  t is created usi
2bd70 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65  ng the SQL.** te
2bd80 78 74 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c  xt "SELECT $abc,
2bd90 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72  :xyz" and if par
2bda0 61 6d 65 74 65 72 20 24 61 62 63 20 69 73 20 62  ameter $abc is b
2bdb0 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20  ound to integer 
2bdc0 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61  2345.** and para
2bdd0 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e  meter :xyz is un
2bde0 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69  bound, then sqli
2bdf0 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72  te3_sql() will r
2be00 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69  eturn.** the ori
2be10 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53  ginal string, "S
2be20 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22  ELECT $abc,:xyz"
2be30 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70   but sqlite3_exp
2be40 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77  anded_sql().** w
2be50 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45  ill return "SELE
2be60 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e  CT 2345,NULL".)^
2be70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2be80 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2be90 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2bea0 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73  urns NULL if ins
2beb0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
2bec0 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65  .** is available
2bed0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
2bee0 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72  ult, or if the r
2bef0 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65  esult would exce
2bf00 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61  ed the.** the ma
2bf10 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e  ximum string len
2bf20 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62  gth determined b
2bf30 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49  y the [SQLITE_LI
2bf40 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a  MIT_LENGTH]..**.
2bf50 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
2bf60 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
2bf70 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2bf80 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65  ption limits the
2bf90 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e   size of.** boun
2bfa0 64 20 70 61 72 61 6d 65 74 65 72 20 65 78 70 61  d parameter expa
2bfb0 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53  nsions.  ^The [S
2bfc0 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45  QLITE_OMIT_TRACE
2bfd0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
2bfe0 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20  * option causes 
2bff0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2c000 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73  _sql() to always
2c010 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a   return NULL..**
2c020 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20  .** ^The string 
2c030 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2c040 74 65 33 5f 73 71 6c 28 50 29 20 69 73 20 6d 61  te3_sql(P) is ma
2c050 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74 65 20  naged by SQLite 
2c060 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  and is.** automa
2c070 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68  tically freed wh
2c080 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 20  en the prepared 
2c090 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e  statement is fin
2c0a0 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  alized..** ^The 
2c0b0 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20  string returned 
2c0c0 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  by sqlite3_expan
2c0d0 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74  ded_sql(P), on t
2c0e0 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a  he other hand,.*
2c0f0 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72  * is obtained fr
2c100 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2c110 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 62  oc()] and must b
2c120 65 20 66 72 65 65 20 62 79 20 74 68 65 20 61 70  e free by the ap
2c130 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20  plication.** by 
2c140 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
2c150 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2c160 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2c170 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
2c180 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2c190 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65  .char *sqlite3_e
2c1a0 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69  xpanded_sql(sqli
2c1b0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2c1c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c1d0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2c1e0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2c1f0 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
2c200 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  base.** METHOD: 
2c210 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2c220 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c230 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
2c240 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2c250 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
2c260 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
2c270 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
2c280 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
2c290 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
2c2a0 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
2c2b0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2c2c0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
2c2d0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2c2e0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2c2f0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2c300 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
2c310 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
2c320 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2c330 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
2c340 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
2c350 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
2c360 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
2c370 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
2c380 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
2c390 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
2c3a0 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
2c3b0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
2c3c0 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
2c3d0 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
2c3e0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2c3f0 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
2c400 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
2c410 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2c420 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
2c430 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
2c440 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
2c450 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
2c460 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
2c470 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
2c480 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2c490 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
2c4a0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2c4b0 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
2c4c0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
2c4d0 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
2c4e0 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
2c4f0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
2c500 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
2c510 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
2c520 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
2c530 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
2c540 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
2c550 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
2c560 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
2c570 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
2c580 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
2c590 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
2c5a0 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
2c5b0 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
2c5c0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
2c5d0 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
2c5e0 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
2c5f0 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
2c600 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
2c610 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
2c620 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
2c630 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
2c640 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
2c650 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
2c660 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
2c670 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
2c680 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
2c690 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
2c6a0 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
2c6b0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
2c6c0 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
2c6d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
2c6e0 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
2c6f0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
2c700 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2c710 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
2c720 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20  n disk..** ^The 
2c730 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2c740 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63  donly() interfac
2c750 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 66  e returns true f
2c760 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65  or [BEGIN] since
2c770 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65  .** [BEGIN] mere
2c780 6c 79 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c  ly sets internal
2c790 20 66 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20   flags, but the 
2c7a0 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d  [BEGIN|BEGIN IMM
2c7b0 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b  EDIATE] and.** [
2c7c0 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c  BEGIN|BEGIN EXCL
2c7d0 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20  USIVE] commands 
2c7e0 64 6f 20 74 6f 75 63 68 20 74 68 65 20 64 61 74  do touch the dat
2c7f0 61 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20  abase and so.** 
2c800 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2c810 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20  donly() returns 
2c820 66 61 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20  false for those 
2c830 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74  commands..*/.int
2c840 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2c850 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73  adonly(sqlite3_s
2c860 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2c870 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2c880 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65  termine If A Pre
2c890 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2c8a0 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a  Has Been Reset.*
2c8b0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2c8c0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2c8d0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
2c8e0 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65  usy(S) interface
2c8f0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
2c900 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a  on-zero) if the.
2c910 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2c920 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65  tement] S has be
2c930 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65  en stepped at le
2c940 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a  ast once using .
2c950 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2c960 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69  (S)] but has nei
2c970 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70  ther run to comp
2c980 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64  letion (returned
2c990 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2c9a0 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  ] from [sqlite3_
2c9b0 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a  step(S)]) nor.**
2c9c0 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
2c9d0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2c9e0 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
2c9f0 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
2ca00 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2ca10 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
2ca20 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2ca30 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
2ca40 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
2ca50 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
2ca60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
2ca70 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
2ca80 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
2ca90 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
2caa0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2cab0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
2cac0 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
2cad0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
2cae0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
2caf0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
2cb00 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2cb10 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
2cb20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
2cb30 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
2cb40 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
2cb50 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
2cb60 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
2cb70 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
2cb80 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
2cb90 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
2cba0 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
2cbb0 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
2cbc0 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
2cbd0 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
2cbe0 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
2cbf0 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
2cc00 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
2cc10 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2cc20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2cc30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2cc40 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
2cc50 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
2cc60 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
2cc70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2cc80 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
2cc90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2cca0 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
2ccb0 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
2ccc0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
2ccd0 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
2cce0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
2ccf0 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
2cd00 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
2cd10 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
2cd20 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
2cd30 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
2cd40 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
2cd50 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
2cd60 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2cd70 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
2cd80 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
2cd90 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
2cda0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
2cdb0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
2cdc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2cdd0 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
2cde0 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
2cdf0 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
2ce00 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
2ce10 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
2ce20 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2ce30 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
2ce40 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
2ce50 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
2ce60 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
2ce70 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2ce80 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
2ce90 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
2cea0 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
2ceb0 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
2cec0 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
2ced0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
2cee0 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
2cef0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2cf00 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  value.  The.** [
2cf10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
2cf20 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  p()] interface c
2cf30 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f  an be used to co
2cf40 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a  nstruct a new .*
2cf50 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  * protected sqli
2cf60 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61  te3_value from a
2cf70 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2cf80 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
2cf90 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
2cfa0 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
2cfb0 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
2cfc0 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
2cfd0 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
2cfe0 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72   held.  An inter
2cff0 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
2d000 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
2d010 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2d020 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
2d030 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
2d040 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
2d050 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2d060 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
2d070 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
2d080 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
2d090 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
2d0a0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
2d0b0 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
2d0c0 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
2d0d0 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
2d0e0 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
2d0f0 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
2d100 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
2d110 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
2d120 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2d130 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
2d140 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2d150 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
2d160 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
2d170 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
2d180 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
2d190 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2d1a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2d1b0 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
2d1c0 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
2d1d0 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
2d1e0 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
2d1f0 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
2d200 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
2d210 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
2d220 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
2d230 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
2d240 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
2d250 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
2d260 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
2d270 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2d280 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
2d290 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
2d2a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2d2b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2d2c0 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
2d2d0 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
2d2e0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
2d2f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
2d300 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2d310 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2d320 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
2d330 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2d340 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
2d350 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2d360 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2d370 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
2d380 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
2d390 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2d3a0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
2d3b0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
2d3c0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
2d3d0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
2d3e0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
2d3f0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
2d400 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d410 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
2d420 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
2d430 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
2d440 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
2d450 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d460 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
2d470 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2d480 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71  sqlite3_value sq
2d490 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
2d4a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
2d4b0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
2d4c0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
2d4d0 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
2d4e0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
2d4f0 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
2d500 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
2d510 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2d520 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
2d530 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
2d540 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2d550 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
2d560 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
2d570 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
2d580 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2d590 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
2d5a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2d5b0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
2d5c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2d5d0 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
2d5e0 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
2d5f0 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
2d600 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2d610 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
2d620 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
2d630 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2d640 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
2d650 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
2d660 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
2d670 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
2d680 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
2d690 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
2d6a0 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
2d6b0 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
2d6c0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2d6d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2d6e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
2d6f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d700 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
2d710 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
2d720 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
2d730 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
2d740 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
2d750 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
2d760 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
2d770 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
2d780 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
2d790 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
2d7a0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
2d7b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2d7c0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
2d7d0 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
2d7e0 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
2d7f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
2d800 61 72 65 5f 76 33 28 29 5d 20 61 6e 64 20 69 74  are_v3()] and it
2d810 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
2d820 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
2d830 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
2d840 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
2d850 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
2d860 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
2d870 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
2d880 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
2d890 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
2d8a0 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
2d8b0 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
2d8c0 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
2d8d0 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
2d8e0 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
2d8f0 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
2d900 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
2d910 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
2d920 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
2d930 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
2d940 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
2d950 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
2d960 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
2d970 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
2d980 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
2d990 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
2d9a0 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
2d9b0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
2d9c0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2d9d0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
2d9e0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
2d9f0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
2da00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2da10 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
2da20 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
2da30 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2da40 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
2da50 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
2da60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2da70 33 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  3()] or its vari
2da80 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
2da90 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2daa0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2dab0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
2dac0 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
2dad0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
2dae0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
2daf0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
2db00 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
2db10 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
2db20 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
2db30 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
2db40 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2db50 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
2db60 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
2db70 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
2db80 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
2db90 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
2dba0 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
2dbb0 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
2dbc0 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
2dbd0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2dbe0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2dbf0 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
2dc00 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
2dc10 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
2dc20 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
2dc30 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
2dc40 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
2dc50 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
2dc60 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
2dc70 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
2dc80 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
2dc90 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
2dca0 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
2dcb0 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
2dcc0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
2dcd0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
2dce0 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
2dcf0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
2dd00 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
2dd10 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2dd20 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
2dd30 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2dd40 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73  text16().** or s
2dd50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2dd60 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
2dd70 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f  nter then the fo
2dd80 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a  urth parameter.*
2dd90 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64  * is ignored and
2dda0 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20   the end result 
2ddb0 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73  is the same as s
2ddc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2ddd0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ()..**.** ^(In t
2dde0 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
2ddf0 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
2de00 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
2de10 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
2de20 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2de30 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
2de40 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
2de50 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
2de60 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
2de70 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
2de80 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
2de90 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
2dea0 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
2deb0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2dec0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2ded0 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
2dee0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2def0 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  6().** is negati
2df00 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e  ve, then the len
2df10 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
2df20 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
2df30 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
2df40 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
2df50 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20   terminator..** 
2df60 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
2df70 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2df80 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
2df90 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2dfa0 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72  .** the behavior
2dfb0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2dfc0 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  * If a non-negat
2dfd0 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  ive fourth param
2dfe0 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64  eter is provided
2dff0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2e000 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _text().** or sq
2e010 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2e020 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  6() or sqlite3_b
2e030 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65  ind_text64() the
2e040 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65  n.** that parame
2e050 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
2e060 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
2e070 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
2e080 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
2e090 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
2e0a0 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
2e0b0 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
2e0c0 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
2e0d0 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
2e0e0 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
2e0f0 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
2e100 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
2e110 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
2e120 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
2e130 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
2e140 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
2e150 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
2e160 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
2e170 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
2e180 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
2e190 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
2e1a0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2e1b0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
2e1c0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c  gument to the BL
2e1d0 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69  OB and string bi
2e1e0 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  nding interfaces
2e1f0 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63  .** is a destruc
2e200 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
2e210 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2e220 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
2e230 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
2e240 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
2e250 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
2e260 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
2e270 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
2e280 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
2e290 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
2e2a0 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c  to bind API fail
2e2b0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  s..** ^If the fi
2e2c0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
2e2d0 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
2e2e0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
2e2f0 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
2e300 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
2e310 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
2e320 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
2e330 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
2e340 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
2e350 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
2e360 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
2e370 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
2e380 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
2e390 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
2e3a0 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
2e3b0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
2e3c0 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
2e3d0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
2e3e0 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
2e3f0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2e400 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
2e410 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61  .** ^The sixth a
2e420 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2e430 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2e440 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a   must be one of.
2e450 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ** [SQLITE_UTF8]
2e460 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  , [SQLITE_UTF16]
2e470 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
2e480 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
2e490 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70  TF16LE].** to sp
2e4a0 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69  ecify the encodi
2e4b0 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69  ng of the text i
2e4c0 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
2e4d0 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68  meter.  If.** th
2e4e0 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
2e4f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2e500 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74  _text64() is not
2e510 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61   one of the.** a
2e520 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68  llowed values sh
2e530 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66  own above, or if
2e540 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
2e550 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a  ng is different.
2e560 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f  ** from the enco
2e570 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62  ding specified b
2e580 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61  y the sixth para
2e590 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
2e5a0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
2e5b0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2e5c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2e5d0 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
2e5e0 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
2e5f0 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
2e600 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
2e610 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
2e620 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
2e630 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
2e640 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
2e650 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
2e660 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
2e670 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
2e680 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
2e690 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
2e6a0 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
2e6b0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
2e6c0 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
2e6d0 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
2e6e0 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
2e6f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
2e700 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
2e710 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
2e720 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
2e730 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
2e740 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
2e750 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
2e760 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
2e770 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
2e780 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2e790 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
2e7a0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
2e7b0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
2e7c0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2e7d0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
2e7e0 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
2e7f0 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
2e800 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
2e810 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
2e820 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
2e830 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
2e840 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
2e850 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
2e860 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
2e870 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
2e880 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
2e890 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
2e8a0 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
2e8b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2e8c0 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
2e8d0 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
2e8e0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2e8f0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
2e900 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
2e910 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
2e920 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
2e930 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e940 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
2e950 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
2e960 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
2e970 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
2e980 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2e990 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
2e9a0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
2e9b0 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
2e9c0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
2e9d0 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
2e9e0 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
2e9f0 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67  LITE_TOOBIG] mig
2ea00 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69  ht be returned i
2ea10 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  f the size of a 
2ea20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a  string or BLOB.*
2ea30 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73  * exceeds limits
2ea40 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c   imposed by [sql
2ea50 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
2ea60 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2ea70 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  ]) or.** [SQLITE
2ea80 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a  _MAX_LENGTH]..**
2ea90 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
2eaa0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2eab0 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
2eac0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
2ead0 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
2eae0 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
2eaf0 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
2eb00 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
2eb10 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2eb20 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2eb30 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
2eb40 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2eb50 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2eb60 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
2eb70 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2eb80 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2eb90 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
2eba0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2ebb0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2ebc0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
2ebd0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
2ebe0 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71  3_bind_blob64(sq
2ebf0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ec00 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73  , const void*, s
2ec10 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
2ec20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ec30 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
2ec40 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
2ec50 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
2ec60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ec70 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74  nt, double);.int
2ec80 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
2ec90 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2eca0 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20   int, int);.int 
2ecb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
2ecc0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2ecd0 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
2ece0 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt64);.int sqlit
2ecf0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
2ed00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
2ed10 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2ed20 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
2ed30 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  stmt*,int,const 
2ed40 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a  char*,int,void(*
2ed50 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2ed60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2ed70 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2ed80 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2ed90 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
2eda0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2edb0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2edc0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2edd0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
2ede0 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
2edf0 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
2ee00 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
2ee10 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69  (*)(void*), unsi
2ee20 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69  gned char encodi
2ee30 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ng);.int sqlite3
2ee40 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
2ee50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2ee60 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
2ee70 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2ee80 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
2ee90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2eea0 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74  int, int n);.int
2eeb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2eec0 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  roblob64(sqlite3
2eed0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
2eee0 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f  ite3_uint64);../
2eef0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2ef00 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
2ef10 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f  ameters.** METHO
2ef20 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2ef30 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
2ef40 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
2ef50 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
2ef60 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d  er of [SQL param
2ef70 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b  eters].** in a [
2ef80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ef90 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  nt].  SQL parame
2efa0 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
2efb0 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
2efc0 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
2efd0 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
2efe0 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
2eff0 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64   as.** placehold
2f000 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74  ers for values t
2f010 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33  hat are [sqlite3
2f020 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75  _bind_blob | bou
2f030 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61  nd].** to the pa
2f040 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61  rameters at a la
2f050 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ter time..**.** 
2f060 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  ^(This routine a
2f070 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
2f080 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
2f090 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d   largest (rightm
2f0a0 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ost).** paramete
2f0b0 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73  r. For all forms
2f0c0 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68   except ?NNN, th
2f0d0 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f  is will correspo
2f0e0 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d  nd to the.** num
2f0f0 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61  ber of unique pa
2f100 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61  rameters.  If pa
2f110 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
2f120 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73  ?NNN form are us
2f130 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79  ed,.** there may
2f140 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20   be gaps in the 
2f150 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  list.)^.**.** Se
2f160 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2f170 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2f180 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
2f190 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2f1a0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
2f1b0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2f1c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2f1d0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
2f1e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2f1f0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c  ameter_count(sql
2f200 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2f210 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
2f220 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72  me Of A Host Par
2f230 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44  ameter.** METHOD
2f240 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2f250 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f260 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2f270 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72  _name(P,N) inter
2f280 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
2f290 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2f2a0 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65  N-th [SQL parame
2f2b0 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65  ter] in the [pre
2f2c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f2d0 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72   P..** ^(SQL par
2f2e0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2f2f0 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
2f300 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
2f310 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
2f320 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
2f330 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
2f340 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
2f350 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
2f360 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
2f370 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
2f380 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
2f390 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
2f3a0 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
2f3b0 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
2f3c0 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a   of the name.)^.
2f3d0 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f  ** ^Parameters o
2f3e0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
2f3f0 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
2f400 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
2f410 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
2f420 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  re referred to a
2f430 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20  s "nameless" or 
2f440 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
2f450 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eters"..**.** ^T
2f460 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
2f470 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
2f480 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
2f490 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2f4a0 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f  value N is out o
2f4b0 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
2f4c0 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e N-th parameter
2f4d0 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
2f4e0 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
2f4f0 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65  turned.  ^The re
2f500 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2f510 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54  .** always in UT
2f520 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
2f530 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
2f540 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
2f550 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
2f560 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
2f570 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
2f580 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  re16()],.** [sql
2f590 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2f5a0 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  2()], or [sqlite
2f5b0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2f5c0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2f5d0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2f5e0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2f5f0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2f600 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2f610 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2f620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2f630 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2f640 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
2f650 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
2f660 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2f670 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f680 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2f690 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
2f6a0 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
2f6b0 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20  A Given Name.** 
2f6c0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2f6d0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  stmt.**.** ^Retu
2f6e0 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
2f6f0 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
2f700 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
2f710 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
2f720 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
2f730 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
2f740 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
2f750 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
2f760 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2f770 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2f780 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
2f790 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2f7a0 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
2f7b0 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
2f7c0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
2f7d0 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
2f7e0 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
2f7f0 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
2f800 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
2f810 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
2f820 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
2f830 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
2f840 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
2f850 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2f860 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a  pare16_v3()]..**
2f870 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2f880 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2f890 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2f8a0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2f8b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2f8c0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2f8d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2f8e0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a  meter_name()]..*
2f8f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
2f900 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2f910 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
2f920 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
2f930 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
2f940 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
2f950 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
2f960 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2f970 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2f980 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2f990 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
2f9a0 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
2f9b0 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
2f9c0 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
2f9d0 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
2f9e0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2f9f0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
2fa00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2fa10 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
2fa20 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
2fa30 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
2fa40 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
2fa50 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2fa60 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
2fa70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2fa80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2fa90 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
2faa0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
2fab0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2fac0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2fad0 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
2fae0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2faf0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2fb00 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
2fb10 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2fb20 74 65 6d 65 6e 74 5d 2e 20 5e 49 66 20 74 68 69  tement]. ^If thi
2fb30 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
2fb40 73 20 30 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  s 0, that means 
2fb50 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65  the .** [prepare
2fb60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 72 65 74  d statement] ret
2fb70 75 72 6e 73 20 6e 6f 20 64 61 74 61 20 28 66 6f  urns no data (fo
2fb80 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
2fb90 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65  DATE])..** ^Howe
2fba0 76 65 72 2c 20 6a 75 73 74 20 62 65 63 61 75 73  ver, just becaus
2fbb0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  e this routine r
2fbc0 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69 76  eturns a positiv
2fbd0 65 20 6e 75 6d 62 65 72 20 64 6f 65 73 20 6e 6f  e number does no
2fbe0 74 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 6f  t.** mean that o
2fbf0 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20  ne or more rows 
2fc00 6f 66 20 64 61 74 61 20 77 69 6c 6c 20 62 65 20  of data will be 
2fc10 72 65 74 75 72 6e 65 64 2e 20 20 5e 41 20 53 45  returned.  ^A SE
2fc20 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a  LECT statement.*
2fc30 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 68 61  * will always ha
2fc40 76 65 20 61 20 70 6f 73 69 74 69 76 65 20 73 71  ve a positive sq
2fc50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2fc60 6e 74 28 29 20 62 75 74 20 64 65 70 65 6e 64 69  nt() but dependi
2fc70 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a 20 57 48 45  ng on the.** WHE
2fc80 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
2fc90 61 69 6e 74 73 20 61 6e 64 20 74 68 65 20 74 61  aints and the ta
2fca0 62 6c 65 20 63 6f 6e 74 65 6e 74 2c 20 69 74 20  ble content, it 
2fcb0 6d 69 67 68 74 20 72 65 74 75 72 6e 20 6e 6f 20  might return no 
2fcc0 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  rows..**.** See 
2fcd0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64  also: [sqlite3_d
2fce0 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  ata_count()].*/.
2fcf0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2fd00 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
2fd10 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2fd20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2fd30 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
2fd40 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20  A Result Set.** 
2fd50 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2fd60 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
2fd70 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
2fd80 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
2fd90 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
2fda0 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
2fdb0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2fdc0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
2fdd0 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73  atement.  ^The s
2fde0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2fdf0 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
2fe00 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2fe10 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
2fe20 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
2fe30 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
2fe40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2fe50 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
2fe60 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
2fe70 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
2fe80 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
2fe90 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2fea0 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
2feb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2fec0 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
2fed0 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
2fee0 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20  statement. ^The 
2fef0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2ff00 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
2ff10 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20  n number.  ^The 
2ff20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
2ff30 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  is number 0..**.
2ff40 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2ff50 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
2ff60 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
2ff70 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
2ff80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2ff90 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
2ffa0 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
2ffb0 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
2ffc0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2ffd0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
2ffe0 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
2fff0 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
30000 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
30010 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
30020 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
30030 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
30040 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
30050 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
30060 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30070 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
30080 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
30090 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
300a0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
300b0 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
300c0 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
300d0 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
300e0 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
300f0 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
30100 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
30110 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
30120 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
30130 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ed..**.** ^The n
30140 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
30150 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
30160 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
30170 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
30180 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
30190 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
301a0 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
301b0 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
301c0 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
301d0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
301e0 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
301f0 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
30200 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
30210 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
30220 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   next..*/.const 
30230 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
30240 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
30250 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
30260 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
30270 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
30280 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
30290 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
302a0 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
302b0 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
302c0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d  uery Result.** M
302d0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
302e0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
302f0 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
30300 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
30310 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62  ermine the datab
30320 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a  ase, table, and.
30330 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ** table column 
30340 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67  that is the orig
30350 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c  in of a particul
30360 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ar result column
30370 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20   in.** [SELECT] 
30380 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54  statement..** ^T
30390 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
303a0 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
303b0 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
303c0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
303d0 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
303e0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
303f0 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73  .  ^The _databas
30400 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
30410 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
30420 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
30430 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
30440 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
30450 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
30460 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
30470 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
30480 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65  mn name..** ^The
30490 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
304a0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
304b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
304c0 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
304d0 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
304e0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
304f0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
30500 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
30510 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
30520 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
30530 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
30540 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
30550 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
30560 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
30570 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
30580 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
30590 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
305a0 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
305b0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ing..**.** ^The 
305c0 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
305d0 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
305e0 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
305f0 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
30600 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
30610 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  column..**.** ^T
30620 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
30630 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  t to these inter
30640 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70  faces is a [prep
30650 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
30660 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
30670 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
30680 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
30690 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
306a0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
306b0 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
306c0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
306d0 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
306e0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
306f0 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
30700 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20  umn is column 0 
30710 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
30720 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
30730 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
30740 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
30750 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
30760 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
30770 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
30780 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
30790 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
307a0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
307b0 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e  turn.** NULL.  ^
307c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
307d0 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
307e0 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
307f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
30800 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f  r.** occurs.  ^O
30810 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
30820 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
30830 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
30840 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a  atabase, table,.
30850 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61  ** or column tha
30860 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
30870 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
30880 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
30890 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68  ^As with all oth
308a0 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
308b0 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65  those whose name
308c0 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20  s end with "16" 
308d0 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
308e0 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
308f0 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66   and the other f
30900 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
30910 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  UTF-8..**.** ^Th
30920 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
30930 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
30940 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
30950 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
30960 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
30970 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
30980 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
30990 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a  or symbol..**.**
309a0 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
309b0 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
309c0 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
309d0 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
309e0 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
309f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30a00 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
30a10 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
30a20 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
30a30 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
30a40 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
30a50 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
30a60 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
30a70 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
30a80 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
30a90 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
30aa0 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
30ab0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
30ac0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30ad0 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
30ae0 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
30af0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
30b00 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
30b10 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
30b20 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
30b30 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
30b40 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
30b50 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
30b60 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
30b70 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
30b80 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
30b90 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
30ba0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
30bb0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
30bc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
30bd0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
30be0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
30bf0 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
30c00 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
30c10 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
30c20 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
30c30 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
30c40 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
30c50 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
30c60 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
30c70 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
30c80 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
30c90 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
30ca0 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
30cb0 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45  ery Result.** ME
30cc0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
30cd0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  mt.**.** ^(The f
30ce0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
30cf0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
30d00 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
30d10 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
30d20 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
30d30 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
30d40 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
30d50 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
30d60 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
30d70 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
30d80 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
30d90 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
30da0 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
30db0 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
30dc0 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
30dd0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
30de0 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
30df0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
30e00 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
30e10 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
30e20 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
30e30 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
30e40 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
30e50 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
30e60 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
30e70 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
30e80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
30e90 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
30ea0 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
30eb0 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
30ec0 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
30ed0 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
30ee0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
30ef0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
30f00 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
30f10 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
30f20 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
30f30 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
30f40 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
30f50 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
30f60 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
30f70 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
30f80 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
30f90 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
30fa0 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
30fb0 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
30fc0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
30fd0 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
30fe0 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
30ff0 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
31000 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
31010 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
31020 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
31030 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
31040 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
31050 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
31060 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
31070 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
31080 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
31090 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
310a0 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
310b0 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
310c0 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
310d0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
310e0 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
310f0 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
31100 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
31110 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
31120 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f  se values..*/.co
31130 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
31140 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
31150 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
31160 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
31170 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
31180 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
31190 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
311a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
311b0 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
311c0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45   Statement.** ME
311d0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
311e0 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  mt.**.** After a
311f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31200 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
31210 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 61 6e  repared using an
31220 79 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  y of.** [sqlite3
31230 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
31240 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
31250 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v3()], [sqlite3
31260 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
31270 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
31280 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
31290 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c   or one of the l
312a0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
312b0 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
312c0 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
312d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
312e0 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  , this function.
312f0 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ** must be calle
31300 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
31310 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
31320 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  the statement..*
31330 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
31340 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
31350 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
31360 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
31370 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
31380 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
31390 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
313a0 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
313b0 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73   "vX" interfaces
313c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
313d0 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c  pare_v3()], [sql
313e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
313f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  )], [sqlite3_pre
31400 70 61 72 65 31 36 5f 76 33 28 29 5d 2c 0a 2a 2a  pare16_v3()],.**
31410 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
31420 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
31430 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
31440 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
31450 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
31460 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
31470 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
31480 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
31490 77 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65  w "vX" interface
314a0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
314b0 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
314c0 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
314d0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
314e0 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
314f0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
31500 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65  **.** ^In the le
31510 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
31520 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
31530 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
31540 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
31550 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
31560 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
31570 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
31580 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
31590 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
315a0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
315b0 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
315c0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
315d0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
315e0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
315f0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
31600 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  as well..**.** ^
31610 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
31620 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
31630 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
31640 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
31650 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
31660 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
31670 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
31680 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d    ^If the statem
31690 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
316a0 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
316b0 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
316c0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
316d0 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
316e0 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
316f0 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
31700 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
31710 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
31720 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e  occurs within an
31730 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
31740 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
31750 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
31760 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
31770 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
31780 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  inuing..**.** ^[
31790 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
317a0 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
317b0 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
317c0 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
317d0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
317e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
317f0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
31800 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
31810 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
31820 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
31830 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
31840 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
31850 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
31860 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
31870 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
31880 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  state..**.** ^If
31890 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
318a0 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
318b0 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
318c0 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
318d0 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
318e0 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
318f0 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
31900 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
31910 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
31920 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
31930 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
31940 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
31950 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
31960 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
31970 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
31980 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
31990 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
319a0 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
319b0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52  *.** ^[SQLITE_ER
319c0 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
319d0 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
319e0 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
319f0 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
31a00 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
31a10 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
31a20 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
31a30 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
31a40 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
31a50 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
31a60 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
31a70 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
31a80 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74  rmsg()]..** ^Wit
31a90 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
31aa0 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
31ab0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
31ac0 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
31ad0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
31ae0 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
31af0 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
31b00 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
31b10 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
31b20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
31b30 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
31b40 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
31b50 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
31b60 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68  tement].  ^In th
31b70 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
31b80 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
31b90 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
31ba0 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
31bb0 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
31bc0 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
31bd0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
31be0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
31bf0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
31c00 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
31c10 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
31c20 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
31c30 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
31c40 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
31c50 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
31c60 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
31c70 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
31c80 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
31c90 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
31ca0 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
31cb0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
31cc0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
31cd0 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
31ce0 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
31cf0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
31d00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
31d10 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
31d20 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
31d30 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
31d40 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
31d50 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65  **.** For all ve
31d60 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
31d70 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75   up to and inclu
31d80 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61  ding 3.6.23.1, a
31d90 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
31da0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61  ite3_reset()] wa
31db0 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72  s required after
31dc0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
31dd0 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
31de0 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  g.** other than 
31df0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66  [SQLITE_ROW] bef
31e00 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65  ore any subseque
31e10 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  nt invocation of
31e20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
31e30 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20  ().  Failure to 
31e40 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
31e50 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
31e60 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
31e70 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72  reset()] would r
31e80 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
31e90 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
31ea0 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  rn from.** sqlit
31eb0 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20  e3_step().  But 
31ec0 61 66 74 65 72 20 5b 76 65 72 73 69 6f 6e 20 33  after [version 3
31ed0 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74 65 6f  .6.23.1] ([dateo
31ee0 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20  f:3.6.23.1],.** 
31ef0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
31f00 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
31f10 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
31f20 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
31f30 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
31f40 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
31f50 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
31f60 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
31f70 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
31f80 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
31f90 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
31fa0 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
31fb0 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
31fc0 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
31fd0 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
31fe0 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
31ff0 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
32000 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
32010 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
32020 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
32030 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
32040 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
32050 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
32060 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
32070 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
32080 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
32090 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
320a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
320b0 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
320c0 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
320d0 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
320e0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
320f0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
32100 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
32110 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
32120 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
32130 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
32140 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
32150 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
32160 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
32170 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
32180 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
32190 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
321a0 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
321b0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
321c0 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
321d0 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
321e0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
321f0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
32200 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
32210 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
32220 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
32230 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
32240 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
32250 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
32260 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 6f 72  prepare_v3()] or
32270 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32280 65 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  e_v2()].** or [s
32290 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
322a0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
322b0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
322c0 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
322d0 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
322e0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
322f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
32300 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
32310 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
32320 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
32330 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
32340 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
32350 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
32360 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
32370 73 65 20 6f 66 20 74 68 65 20 22 76 58 22 20 69  se of the "vX" i
32380 6e 74 65 72 66 61 63 65 73 20 69 73 20 72 65 63  nterfaces is rec
32390 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74  ommended..*/.int
323a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
323b0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
323c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
323d0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
323e0 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
323f0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
32400 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
32410 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
32420 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
32430 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
32440 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
32450 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
32460 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
32470 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
32480 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
32490 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
324a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
324b0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
324c0 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
324d0 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
324e0 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
324f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
32500 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
32510 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
32520 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
32530 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
32540 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
32550 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
32560 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
32570 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
32580 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
32590 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
325a0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
325b0 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
325c0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
325d0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
325e0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
325f0 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
32600 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
32610 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
32620 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
32630 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
32640 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
32650 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
32660 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
32670 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
32680 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
32690 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
326a0 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
326b0 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
326c0 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
326d0 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
326e0 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
326f0 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
32700 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
32710 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
32720 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
32730 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
32740 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  n_count()].*/.in
32750 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
32760 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
32770 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
32780 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
32790 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
327a0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
327b0 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
327c0 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69   ^(Every value i
327d0 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
327e0 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
327f0 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
32800 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
32810 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
32820 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
32830 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
32840 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
32850 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
32860 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
32870 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
32880 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
32890 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
328a0 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
328b0 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
328c0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
328d0 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
328e0 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
328f0 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
32900 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
32910 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
32920 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
32930 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
32940 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
32950 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
32960 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
32970 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
32980 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
32990 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c  TEXT, not.** SQL
329a0 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
329b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
329c0 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
329d0 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
329e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
329f0 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
32a00 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
32a10 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
32a20 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
32a30 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
32a40 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
32a50 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
32a60 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
32a70 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
32a80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32a90 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72  Result Values Fr
32aa0 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45  om A Query.** KE
32ab0 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20  YWORDS: {column 
32ac0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
32ad0 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
32ae0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
32af0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
32b00 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
32b10 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
32b20 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
32b30 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
32b40 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
32b50 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
32b60 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
32b70 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
32b80 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
32b90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
32ba0 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
32bb0 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
32bc0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
32bd0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
32be0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
32bf0 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 6f  _prepare_v3()] o
32c00 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
32c10 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
32c20 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
32c30 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
32c40 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
32c50 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
32c60 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
32c70 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
32c80 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
32c90 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
32ca0 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
32cb0 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
32cc0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
32cd0 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
32ce0 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
32cf0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
32d00 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
32d10 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
32d20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
32d30 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
32d40 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
32d50 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
32d60 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
32d70 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
32d80 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
32d90 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
32da0 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
32db0 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
32dc0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
32dd0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
32de0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
32df0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
32e00 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
32e10 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
32e20 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
32e30 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
32e40 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
32e50 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
32e60 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
32e70 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
32e80 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
32e90 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
32ea0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
32eb0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
32ec0 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
32ed0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
32ee0 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
32ef0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
32f00 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
32f10 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
32f20 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
32f30 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
32f40 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
32f50 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
32f60 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
32f70 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
32f80 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
32f90 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
32fa0 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
32fb0 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
32fc0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
32fd0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
32fe0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
32ff0 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
33000 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
33010 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
33020 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
33030 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
33040 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
33050 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
33060 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
33070 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
33080 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
33090 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
330a0 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
330b0 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
330c0 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
330d0 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
330e0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
330f0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
33100 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
33110 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
33120 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
33130 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
33140 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
33150 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
33160 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
33170 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
33180 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
33190 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
331a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
331b0 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
331c0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
331d0 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
331e0 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
331f0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
33200 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
33210 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
33220 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
33230 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
33240 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
33250 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
33260 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
33270 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
33280 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
33290 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
332a0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
332b0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
332c0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
332d0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
332e0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
332f0 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
33300 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
33310 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
33320 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
33330 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
33340 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
33350 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
33360 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33370 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
33380 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
33390 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
333a0 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
333b0 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
333c0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
333d0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
333e0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
333f0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
33400 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
33410 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
33420 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
33430 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
33440 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
33450 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
33460 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
33470 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
33480 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
33490 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
334a0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
334b0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
334c0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
334d0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73  ult is a UTF-8 s
334e0 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
334f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
33500 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  16() converts.**
33510 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
33520 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72  TF-16 and then r
33530 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
33540 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
33550 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
33560 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
33570 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
33580 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75  lumn_bytes16() u
33590 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
335a0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
335b0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
335c0 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74  e to a UTF-16 st
335d0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
335e0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
335f0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
33600 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
33610 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
33620 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
33630 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
33640 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
33650 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73  *.** ^The values
33660 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
33670 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
33680 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73  es()] and .** [s
33690 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
336a0 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20  tes16()] do not 
336b0 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
336c0 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20   terminators at 
336d0 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
336e0 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
336f0 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
33700 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
33710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
33720 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
33730 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
33740 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74  bytes16()] are t
33750 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
33760 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
33770 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
33780 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
33790 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
337a0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
337b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
337c0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
337d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
337e0 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
337f0 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
33800 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
33810 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
33820 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
33830 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
33840 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
33850 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
33860 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
33870 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a  *.** <b>Warning:
33880 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74  </b> ^The object
33890 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
338a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
338b0 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
338c0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
338d0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
338e0 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68  t.  In a multith
338f0 72 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65  readed environme
33900 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74  nt,.** an unprot
33910 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
33920 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f  lue object may o
33930 6e 6c 79 20 62 65 20 75 73 65 64 20 73 61 66 65  nly be used safe
33940 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ly with.** [sqli
33950 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
33960 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
33970 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
33980 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
33990 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
339a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
339b0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
339c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
339d0 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
339e0 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
339f0 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
33a00 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
33a10 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
33a20 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
33a30 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
33a40 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
33a50 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
33a60 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
33a70 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
33a80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
33a90 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
33aa0 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
33ab0 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
33ac0 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65  iate.  ^For.** e
33ad0 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
33ae0 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
33af0 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
33b00 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
33b10 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
33b20 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
33b30 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
33b40 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
33b50 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
33b60 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
33b70 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f  cally.  ^(The fo
33b80 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
33b90 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
33ba0 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
33bb0 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
33bc0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
33bd0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
33be0 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
33bf0 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
33c00 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
33c10 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
33c20 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
33c30 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
33c40 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
33c50 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
33c60 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
33c70 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
33c80 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
33c90 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
33ca0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
33cb0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
33cc0 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c   Result is a NUL
33cd0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
33ce0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
33cf0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
33d00 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
33d10 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
33d20 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
33d30 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
33d40 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
33d50 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
33d60 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
33d70 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
33d80 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
33d90 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
33da0 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
33db0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
33dc0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
33dd0 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45  td> Same as INTE
33de0 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
33df0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
33e00 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
33e10 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
33e20 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
33e30 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
33e40 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
33e50 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
33e60 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
33e70 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
33e80 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
33e90 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c  td> [CAST] to BL
33ea0 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  OB.** <tr><td>  
33eb0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
33ec0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
33ed0 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
33ee0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
33ef0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
33f00 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
33f10 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
33f20 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
33f30 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
33f40 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
33f50 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
33f60 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
33f70 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
33f80 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
33f90 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
33fa0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41  LOAT    <td> [CA
33fb0 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c  ST] to REAL.** <
33fc0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
33fd0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
33fe0 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
33ff0 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
34000 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
34010 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
34020 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  >)^.**.** Note t
34030 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
34040 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
34050 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
34060 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
34070 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
34080 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
34090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
340a0 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
340b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
340c0 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
340d0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
340e0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
340f0 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
34100 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
34110 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
34120 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
34130 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
34140 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
34150 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
34160 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
34170 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
34180 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
34190 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
341a0 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
341b0 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
341c0 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
341d0 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
341e0 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
341f0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
34200 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
34210 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
34220 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
34230 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
34240 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
34250 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
34260 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
34270 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
34280 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
34290 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
342a0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
342b0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
342c0 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
342d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
342e0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
342f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
34300 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
34310 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
34320 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
34330 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
34340 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
34350 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20  ** ^Conversions 
34360 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
34370 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
34380 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
34390 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
343a0 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
343b0 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
343c0 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
343d0 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
343e0 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
343f0 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
34400 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73  inter references
34410 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
34420 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
34430 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
34440 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
34450 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
34460 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
34470 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
34480 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
34490 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
344a0 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
344b0 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
344c0 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
344d0 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79  he safest policy
344e0 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
344f0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
34500 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
34510 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
34520 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
34530 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
34540 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
34550 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
34560 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
34570 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
34580 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
34590 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
345a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
345b0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
345c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
345d0 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
345e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
345f0 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
34600 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
34610 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
34620 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
34630 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
34640 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
34650 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
34660 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
34670 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
34680 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
34690 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
346a0 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
346b0 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
346c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
346d0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
346e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
346f0 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
34700 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
34710 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
34720 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
34730 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
34740 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
34750 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
34760 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
34770 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
34780 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
34790 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
347a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
347b0 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
347c0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
347d0 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
347e0 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73  ** ^The pointers
347f0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
34800 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
34810 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
34820 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
34830 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
34840 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
34850 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
34860 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
34870 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34880 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
34890 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63  ^The memory spac
348a0 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
348b0 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
348c0 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
348d0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
348e0 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73  <em>not</em> pas
348f0 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
34900 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
34910 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
34920 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
34930 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
34940 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
34950 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
34960 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65  .**.** ^(If a me
34970 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
34980 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
34990 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
349a0 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
349b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
349c0 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
349d0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
349e0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
349f0 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
34a00 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
34a10 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
34a20 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
34a30 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
34a40 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
34a50 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
34a60 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
34a70 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
34a80 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f  _NOMEM].)^.*/.co
34a90 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
34aa0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
34ab0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
34ac0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
34ad0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
34ae0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
34af0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
34b00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34b10 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
34b20 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
34b30 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
34b40 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
34b50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
34b60 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
34b70 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
34b80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
34b90 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
34ba0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
34bb0 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
34bc0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
34bd0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
34be0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
34bf0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
34c00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
34c10 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
34c20 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
34c30 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
34c40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
34c50 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
34c60 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
34c70 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
34c80 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
34c90 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
34ca0 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
34cb0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
34cc0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
34cd0 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
34ce0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
34cf0 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54  t Object.** DEST
34d00 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f  RUCTOR: sqlite3_
34d10 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
34d20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34d30 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
34d40 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
34d50 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
34d60 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
34d70 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
34d80 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65  valuation of the
34d90 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75   statement encou
34da0 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73  ntered no errors
34db0 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74  .** or if the st
34dc0 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72  atement is never
34dd0 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c   been evaluated,
34de0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69   then sqlite3_fi
34df0 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73  nalize() returns
34e00 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20  .** SQLITE_OK.  
34e10 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
34e20 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
34e30 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61  f statement S fa
34e40 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  iled, then.** sq
34e50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
34e60 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70  ) returns the ap
34e70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
34e80 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
34e90 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
34ea0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e]..**.** ^The s
34eb0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
34ec0 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  S) routine can b
34ed0 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
34ee0 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20  point during.** 
34ef0 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f  the life cycle o
34f00 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
34f10 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66  ement] S:.** bef
34f20 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20  ore statement S 
34f30 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65  is ever evaluate
34f40 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20  d, after.** one 
34f50 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f  or more calls to
34f60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34f70 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79  )], or after any
34f80 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c   call.** to [sql
34f90 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67  ite3_step()] reg
34fa0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
34fb0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74  er or not the st
34fc0 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63  atement has.** c
34fd0 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
34fe0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b  on..**.** ^Invok
34ff0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ing sqlite3_fina
35000 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c  lize() on a NULL
35010 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
35020 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
35030 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
35040 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a  ion must finaliz
35050 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65  e every [prepare
35060 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
35070 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a  order to avoid.*
35080 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73  * resource leaks
35090 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76  .  It is a griev
350a0 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68  ous error for th
350b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
350c0 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61   try to use.** a
350d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
350e0 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
350f0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
35100 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70    Any use of a p
35110 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
35120 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
35130 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
35140 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75   can result in u
35150 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20  ndefined and.** 
35160 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
35170 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67  vior such as seg
35180 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20  faults and heap 
35190 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69  corruption..*/.i
351a0 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
351b0 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
351c0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
351d0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
351e0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
351f0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
35200 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
35210 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  stmt.**.** The s
35220 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66  qlite3_reset() f
35230 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
35240 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72  d to reset a [pr
35250 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
35260 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b  ].** object back
35270 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
35280 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20  state, ready to 
35290 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a  be re-executed..
352a0 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74  ** ^Any SQL stat
352b0 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
352c0 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
352d0 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
352e0 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
352f0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
35300 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
35310 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
35320 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
35330 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
35340 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
35350 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
35360 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  gs..**.** ^The [
35370 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
35380 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
35390 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
353a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
353b0 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67   back to the beg
353c0 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72  inning of its pr
353d0 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ogram..**.** ^If
353e0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
353f0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
35400 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
35410 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
35420 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74  statement] S ret
35430 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
35440 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  W] or [SQLITE_DO
35450 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73  NE],.** or if [s
35460 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
35470 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
35480 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
35490 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69  S,.** then [sqli
354a0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
354b0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
354c0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
354d0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
354e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
354f0 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
35500 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
35510 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74  ement] S indicat
35520 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65  ed an error, the
35530 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  n.** [sqlite3_re
35540 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
35550 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
35560 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
35570 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
35580 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
35590 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68  face does not ch
355a0 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a  ange the values.
355b0 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74  ** of any [sqlit
355c0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
355d0 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70  dings] on the [p
355e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
355f0 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  t] S..*/.int sql
35600 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
35610 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
35620 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35630 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
35640 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
35650 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
35660 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  {function creati
35670 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20  on routines}.** 
35680 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
35690 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
356a0 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20  QL function}.** 
356b0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
356c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
356d0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  QL functions}.**
356e0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
356f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
35700 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74  nctions (collect
35710 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22  ively known as "
35720 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
35730 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20  n routines").** 
35740 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
35750 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
35760 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74   aggregates or t
35770 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
35780 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78  ehavior.** of ex
35790 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
357a0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
357b0 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69  es.  The only di
357c0 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65  fferences betwee
357d0 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69  n.** these routi
357e0 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74  nes are the text
357f0 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74   encoding expect
35800 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65  ed for.** the se
35810 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
35820 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
35830 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63  function being c
35840 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74  reated).** and t
35850 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61  he presence or a
35860 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74  bsence of a dest
35870 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
35880 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  for.** the appli
35890 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
358a0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
358b0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
358c0 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
358d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
358e0 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
358f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
35900 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
35910 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
35920 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
35930 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
35940 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
35950 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35960 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
35970 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
35980 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
35990 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
359a0 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rately..**.** ^T
359b0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
359c0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
359d0 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
359e0 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
359f0 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
35a00 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
35a10 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
35a20 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
35a30 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a  tes in a UTF-8.*
35a40 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  * representation
35a50 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
35a60 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
35a70 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  or.  ^Note that 
35a80 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67  the name.** leng
35a90 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55  th limit is in U
35aa0 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20  TF-8 bytes, not 
35ab0 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55  characters nor U
35ac0 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a  TF-16 bytes.  .*
35ad0 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74  * ^Any attempt t
35ae0 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
35af0 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
35b00 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
35b10 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
35b20 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72  _MISUSE] being r
35b30 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
35b40 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
35b50 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
35b60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
35b70 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
35b80 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
35b90 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
35ba0 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
35bb0 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
35bc0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
35bd0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
35be0 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
35bf0 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
35c00 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
35c10 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
35c20 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
35c30 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
35c40 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
35c50 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
35c60 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
35c70 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
35c80 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
35c90 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
35ca0 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
35cb0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
35cc0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
35cd0 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
35ce0 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
35cf0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
35d00 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
35d10 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
35d20 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
35d30 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
35d40 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
35d50 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69  n should set thi
35d60 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
35d70 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  * [SQLITE_UTF16L
35d80 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69  E] if the functi
35d90 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
35da0 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73  n invokes .** [s
35db0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
35dc0 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16le()] on an i
35dd0 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45  nput, or [SQLITE
35de0 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65  _UTF16BE] if the
35df0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
35e00 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69  on invokes [sqli
35e10 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
35e20 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75  be()] on an inpu
35e30 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  t, or.** [SQLITE
35e40 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69  _UTF16] if [sqli
35e50 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
35e60 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20  ()] is used, or 
35e70 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a  [SQLITE_UTF8].**
35e80 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68   otherwise.  ^Th
35e90 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
35ea0 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
35eb0 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
35ec0 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69  imes using.** di
35ed0 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65  fferent preferre
35ee0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
35ef0 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  , with different
35f00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
35f10 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63   for.** each enc
35f20 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20  oding..** ^When 
35f30 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
35f40 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
35f50 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
35f60 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
35f70 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
35f80 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
35f90 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
35fa0 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
35fb0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
35fc0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
35fd0 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69  rameter may opti
35fe0 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77  onally be ORed w
35ff0 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45  ith [SQLITE_DETE
36000 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f  RMINISTIC].** to
36010 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65   signal that the
36020 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61   function will a
36030 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
36040 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76   same result giv
36050 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69  en.** the same i
36060 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73  nputs within a s
36070 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
36080 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66  ent.  Most SQL f
36090 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20  unctions are.** 
360a0 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20  deterministic.  
360b0 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61  The built-in [ra
360c0 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63  ndom()] SQL func
360d0 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70  tion is an examp
360e0 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74  le of a.** funct
360f0 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ion that is not 
36100 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20  deterministic.  
36110 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79  The SQLite query
36120 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65   planner is able
36130 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61   to.** perform a
36140 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69  dditional optimi
36150 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72  zations on deter
36160 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f  ministic functio
36170 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66  ns, so use.** of
36180 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54   the [SQLITE_DET
36190 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67  ERMINISTIC] flag
361a0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
361b0 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a  where possible..
361c0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74  **.** ^(The fift
361d0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
361e0 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
361f0 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
36200 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
36210 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
36220 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
36230 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
36240 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
36250 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  data()].)^.**.**
36260 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76   ^The sixth, sev
36270 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20  enth and eighth 
36280 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
36290 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
362a0 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
362b0 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
362c0 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
362d0 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
362e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
362f0 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41  ** aggregate. ^A
36300 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
36310 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
36320 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
36330 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
36340 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e  callback only; N
36350 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73  ULL pointers mus
36360 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
36370 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  he xStep and xFi
36380 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  nal.** parameter
36390 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65  s. ^An aggregate
363a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
363b0 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
363c0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65  entation of xSte
363d0 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
363e0 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  and NULL pointer
363f0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
36400 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64  for xFunc. ^To d
36410 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
36420 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
36430 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
36440 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  pass NULL pointe
36450 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  rs for all three
36460 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
36470 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lbacks..**.** ^(
36480 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72  If the ninth par
36490 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
364a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
364b0 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55  n_v2() is not NU
364c0 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  LL,.** then it i
364d0 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  s destructor for
364e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
364f0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a   data pointer. .
36500 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  ** The destructo
36510 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  r is invoked whe
36520 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  n the function i
36530 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65  s deleted, eithe
36540 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76  r by being.** ov
36550 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e  erloaded or when
36560 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
36570 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
36580 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72  )^.** ^The destr
36590 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e  uctor is also in
365a0 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c  voked if the cal
365b0 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
365c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
365d0 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e  v2() fails..** ^
365e0 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63  When the destruc
365f0 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  tor callback of 
36600 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65  the tenth parame
36610 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ter is invoked, 
36620 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  it.** is passed 
36630 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
36640 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70  t which is a cop
36650 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  y of the applica
36660 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f  tion data .** po
36670 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
36680 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  the fifth parame
36690 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
366a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
366b0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  2()..**.** ^It i
366c0 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
366d0 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
366e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
366f0 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
36700 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
36710 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
36720 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
36730 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
36740 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
36750 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
36760 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
36770 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77  ings.  ^SQLite w
36780 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
36790 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
367a0 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  at most closely 
367b0 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
367c0 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
367d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
367e0 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69  used.  ^A functi
367f0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
36800 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
36810 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
36820 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
36830 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
36840 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
36850 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
36860 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
36870 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  .  ^A function w
36880 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
36890 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
368a0 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
368b0 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
368c0 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
368d0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
368e0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
368f0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
36900 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20  ferent.  .** ^A 
36910 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
36920 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
36930 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65  erence is betwee
36940 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54  n UTF16le and UT
36950 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c  F16be.** is a cl
36960 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  oser match than 
36970 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
36980 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
36990 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62  fference is.** b
369a0 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20  etween UTF8 and 
369b0 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75  UTF16..**.** ^Bu
369c0 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
369d0 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64   may be overload
369e0 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63  ed by new applic
369f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
36a00 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nctions..**.** ^
36a10 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
36a20 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
36a30 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
36a40 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
36a50 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
36a60 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
36a70 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
36a80 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
36a90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
36aa0 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
36ab0 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
36ac0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
36ad0 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
36ae0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
36af0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
36b00 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
36b10 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
36b20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
36b30 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
36b40 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
36b50 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
36b60 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
36b70 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
36b80 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
36b90 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
36ba0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
36bb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36bc0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
36bd0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
36be0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
36bf0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
36c00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
36c10 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
36c20 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
36c30 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
36c40 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
36c50 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
36c60 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
36c70 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
36c80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36c90 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
36ca0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
36cb0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
36cc0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
36cd0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
36ce0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
36cf0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36d00 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
36d10 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
36d20 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
36d30 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
36d40 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
36d50 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
36d60 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
36d70 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
36d80 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
36d90 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
36da0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
36db0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
36dc0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
36dd0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
36de0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
36df0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
36e00 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76  3_context*),.  v
36e10 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
36e20 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
36e30 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
36e40 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
36e50 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
36e60 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
36e70 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
36e80 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
36e90 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
36ea0 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
36eb0 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
36ec0 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
36ed0 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d        1    /* IM
36ee0 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36  P: R-37514-35566
36ef0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
36f00 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
36f10 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    2    /* IMP: R
36f20 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a  -03371-37637 */.
36f30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
36f40 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 20  TF16BE        3 
36f50 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39     /* IMP: R-519
36f60 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66  71-34154 */.#def
36f70 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
36f80 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
36f90 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
36fa0 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
36fb0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
36fc0 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
36fd0 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23   Deprecated */.#
36fe0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
36ff0 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
37000 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
37010 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
37020 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
37030 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
37040 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  Flags.**.** Thes
37050 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20  e constants may 
37060 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72  be ORed together
37070 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
37080 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65  QLITE_UTF8 | pre
37090 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
370a0 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75  ding] as the fou
370b0 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rth argument.** 
370c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
370d0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
370e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
370f0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  function16()], o
37100 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
37110 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
37120 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
37130 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
37140 53 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f  STIC    0x800../
37150 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
37160 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69  eprecated Functi
37170 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ons.** DEPRECATE
37180 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  D.**.** These fu
37190 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70  nctions are [dep
371a0 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72  recated].  In or
371b0 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a  der to maintain.
371c0 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
371d0 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
371e0 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73  older code, thes
371f0 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74  e functions cont
37200 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73  inue .** to be s
37210 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76  upported.  Howev
37220 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  er, new applicat
37230 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69  ions should avoi
37240 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  d.** the use of 
37250 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
37260 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70    To encourage p
37270 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76  rogrammers to av
37280 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e  oid.** these fun
37290 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20  ctions, we will 
372a0 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74  not explain what
372b0 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66   they do..*/.#if
372c0 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
372d0 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49  _DEPRECATED.SQLI
372e0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
372f0 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
37300 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
37310 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
37320 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
37330 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  nt sqlite3_expir
37340 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
37350 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
37360 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
37370 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
37380 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
37390 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
373a0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
373b0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
373c0 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76  global_recover(v
373d0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
373e0 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c  RECATED void sql
373f0 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
37400 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  nup(void);.SQLIT
37410 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
37420 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
37430 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
37440 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
37450 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20  4,int),.        
37460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
37470 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
37480 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
37490 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
374a0 69 6e 69 6e 67 20 53 51 4c 20 56 61 6c 75 65 73  ining SQL Values
374b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
374c0 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20  te3_value.**.** 
374d0 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69  The C-language i
374e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
374f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
37500 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73  nd aggregates us
37510 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f  es.** this set o
37520 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  f interface rout
37530 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74  ines to access t
37540 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c  he parameter val
37550 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75  ues on.** the fu
37560 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
37570 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ate.  .**.** The
37580 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
37590 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
375a0 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
375b0 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
375c0 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
375d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
375e0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
375f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
37600 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
37610 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
37620 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
37630 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
37640 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
37650 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
37660 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
37670 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
37680 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
37690 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  * [protected sql
376a0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
376b0 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f  cts.  There is o
376c0 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ne [sqlite3_valu
376d0 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a  e] object for.**
376e0 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20   each parameter 
376f0 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
37700 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ion.  These rout
37710 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
37720 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75  .** extract valu
37730 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
37740 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
37750 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  cts..**.** These
37760 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f   routines work o
37770 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63  nly with [protec
37780 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
37790 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41  e] objects..** A
377a0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ny attempt to us
377b0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
377c0 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   on an [unprotec
377d0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
377e0 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73  e].** object res
377f0 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
37800 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  d behavior..**.*
37810 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
37820 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65  s work just like
37830 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
37840 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  ng [column acces
37850 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20  s functions].** 
37860 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 73  except that thes
37870 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20  e routines take 
37880 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63  a single [protec
37890 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
378a0 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69  e] object.** poi
378b0 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  nter instead of 
378c0 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  a [sqlite3_stmt*
378d0 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
378e0 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
378f0 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  number..**.** ^T
37900 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
37910 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66  _text16() interf
37920 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55  ace extracts a U
37930 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20  TF-16 string.** 
37940 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
37950 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te-order of the 
37960 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e  host machine.  ^
37970 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
37980 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
37990 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
379a0 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
379b0 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
379c0 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ct UTF-16 string
379d0 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
379e0 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
379f0 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
37a00 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
37a10 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
37a20 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
37a30 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
37a40 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
37a50 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
37a60 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
37a70 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
37a80 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
37a90 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
37aa0 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
37ab0 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
37ac0 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
37ad0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
37ae0 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
37af0 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
37b00 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
37b10 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20  * words, if the 
37b20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
37b30 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
37b40 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
37b50 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
37b60 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
37b70 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
37b80 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
37b90 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
37ba0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
37bb0 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
37bc0 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
37bd0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73  d.)^.**.** Pleas
37be0 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72  e pay particular
37bf0 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68   attention to th
37c00 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20  e fact that the 
37c10 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64  pointer returned
37c20 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
37c30 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c  3_value_blob()],
37c40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
37c50 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  text()], or.** [
37c60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37c70 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69  xt16()] can be i
37c80 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20  nvalidated by a 
37c90 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
37ca0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
37cb0 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b  alue_bytes()], [
37cc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
37cd0 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  tes16()], [sqlit
37ce0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
37cf0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
37d00 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
37d10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
37d20 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
37d30 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
37d40 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a  ame thread as.**
37d50 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
37d60 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20  n that supplied 
37d70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
37d80 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e  ue*] parameters.
37d90 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
37da0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
37db0 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
37dc0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
37dd0 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
37de0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
37df0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
37e00 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
37e10 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73  alue*);.double s
37e20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
37e30 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble(sqlite3_valu
37e40 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
37e50 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
37e60 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69  e3_value*);.sqli
37e70 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
37e80 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
37e90 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
37ea0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
37eb0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ar *sqlite3_valu
37ec0 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
37ed0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
37ee0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
37ef0 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
37f00 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
37f10 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
37f20 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
37f30 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
37f40 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
37f50 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
37f60 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
37f70 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
37f80 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33  lue_type(sqlite3
37f90 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
37fa0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
37fb0 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33  ric_type(sqlite3
37fc0 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
37fd0 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 69   CAPI3REF: Findi
37fe0 6e 67 20 54 68 65 20 53 75 62 74 79 70 65 20 4f  ng The Subtype O
37ff0 66 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20  f SQL Values.** 
38000 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
38010 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  value.**.** The 
38020 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75  sqlite3_value_su
38030 62 74 79 70 65 28 56 29 20 66 75 6e 63 74 69 6f  btype(V) functio
38040 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 75  n returns the su
38050 62 74 79 70 65 20 66 6f 72 0a 2a 2a 20 61 6e 20  btype for.** an 
38060 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
38070 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
38080 6e 5d 20 61 72 67 75 6d 65 6e 74 20 56 2e 20 20  n] argument V.  
38090 54 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 69  The subtype.** i
380a0 6e 66 6f 72 6d 61 74 69 6f 6e 20 63 61 6e 20 62  nformation can b
380b0 65 20 75 73 65 64 20 74 6f 20 70 61 73 73 20 61  e used to pass a
380c0 20 6c 69 6d 69 74 65 64 20 61 6d 6f 75 6e 74 20   limited amount 
380d0 6f 66 20 63 6f 6e 74 65 78 74 20 66 72 6f 6d 0a  of context from.
380e0 2a 2a 20 6f 6e 65 20 53 51 4c 20 66 75 6e 63 74  ** one SQL funct
380f0 69 6f 6e 20 74 6f 20 61 6e 6f 74 68 65 72 2e 20  ion to another. 
38100 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
38110 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 70 65  3_result_subtype
38120 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  ()].** routine t
38130 6f 20 73 65 74 20 74 68 65 20 73 75 62 74 79 70  o set the subtyp
38140 65 20 66 6f 72 20 74 68 65 20 72 65 74 75 72 6e  e for the return
38150 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c   value of an SQL
38160 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
38170 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 6e 6f   SQLite makes no
38180 20 75 73 65 20 6f 66 20 73 75 62 74 79 70 65 20   use of subtype 
38190 69 74 73 65 6c 66 2e 20 20 49 74 20 6d 65 72 65  itself.  It mere
381a0 6c 79 20 70 61 73 73 65 73 20 74 68 65 20 73 75  ly passes the su
381b0 62 74 79 70 65 0a 2a 2a 20 66 72 6f 6d 20 74 68  btype.** from th
381c0 65 20 72 65 73 75 6c 74 20 6f 66 20 6f 6e 65 20  e result of one 
381d0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
381e0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
381f0 6e 5d 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  n] into the.** i
38200 6e 70 75 74 20 6f 66 20 61 6e 6f 74 68 65 72 2e  nput of another.
38210 0a 2a 2f 0a 75 6e 73 69 67 6e 65 64 20 69 6e 74  .*/.unsigned int
38220 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73   sqlite3_value_s
38230 75 62 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  ubtype(sqlite3_v
38240 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
38250 41 50 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e  API3REF: Copy An
38260 64 20 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65  d Free SQL Value
38270 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
38280 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a  ite3_value.**.**
38290 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
382a0 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72  lue_dup(V) inter
382b0 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
382c0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
382d0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
382e0 63 74 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73  ct D and returns
382f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
38300 61 74 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b  at copy.  ^The [
38310 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72  sqlite3_value] r
38320 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20  eturned.** is a 
38330 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
38340 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
38350 20 65 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70   even if the inp
38360 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54  ut is not..** ^T
38370 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
38380 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63  _dup(V) interfac
38390 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69  e returns NULL i
383a0 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69  f V is NULL or i
383b0 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
383c0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a  location fails..
383d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
383e0 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29  e3_value_free(V)
383f0 20 69 6e 74 65 72 66 61 63 65 20 66 72 65 65 73   interface frees
38400 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   an [sqlite3_val
38410 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72  ue] object.** pr
38420 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
38430 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
38440 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e  value_dup()].  ^
38450 49 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70  If V is a NULL p
38460 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73  ointer.** then s
38470 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65  qlite3_value_fre
38480 65 28 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65  e(V) is a harmle
38490 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 73 71 6c  ss no-op..*/.sql
384a0 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
384b0 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 63 6f  te3_value_dup(co
384c0 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
384d0 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
384e0 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 73 71 6c  3_value_free(sql
384f0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
38500 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
38510 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
38520 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
38530 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
38540 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
38550 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * Implementation
38560 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  s of aggregate S
38570 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
38580 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
38590 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
385a0 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ory for storing 
385b0 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
385c0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
385d0 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
385e0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
385f0 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73  (C,N) routine is
38600 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20   called .** for 
38610 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
38620 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c  regate function,
38630 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63   SQLite.** alloc
38640 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79  ates N of memory
38650 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
38660 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
38670 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
38680 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65  ** to the new me
38690 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64  mory. ^On second
386a0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
386b0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
386c0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
386d0 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
386e0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
386f0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
38700 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
38710 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
38720 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65  .  Sqlite3_aggre
38730 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69  gate_context() i
38740 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61  s normally.** ca
38750 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  lled once for ea
38760 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ch invocation of
38770 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62   the xStep callb
38780 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65  ack and then one
38790 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68  .** last time wh
387a0 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  en the xFinal ca
387b0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
387c0 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f  d.  ^(When no ro
387d0 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61  ws match.** an a
387e