/ Hex Artifact Content
Login

Artifact 47e4df9bae9d474991a7e1468aab5cb1b6d49def:


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 76 65 72 73 69 6f 6e  ** Since version
0f00: 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20   3.6.18, SQLite 
0f10: 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73 20  source code has 
0f20: 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74  been stored in t
0f30: 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68  he.** <a href="h
0f40: 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c  ttp://www.fossil
0f50: 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69  -scm.org/">Fossi
0f60: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  l configuration 
0f70: 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79  management.** sy
0f80: 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20  stem</a>.  ^The 
0f90: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
0fa0: 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73   macro evaluates
0fb0: 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20   to.** a string 
0fc0: 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65 73  which identifies
0fd0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 68   a particular ch
0fe0: 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65  eck-in of SQLite
0ff0: 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63  .** within its c
1000: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e  onfiguration man
1010: 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20  agement system. 
1020: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55   ^The SQLITE_SOU
1030: 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67  RCE_ID.** string
1040: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
1050: 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74  te and time of t
1060: 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43  he check-in (UTC
1070: 29 20 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a  ) and an SHA1.**
1080: 20 68 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74   hash of the ent
1090: 69 72 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ire source tree.
10a0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
10b0: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
10c0: 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sion()],.** [sql
10d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
10e0: 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69  number()], [sqli
10f0: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c  te3_sourceid()],
1100: 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73  .** [sqlite_vers
1110: 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
1120: 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e  te_source_id()].
1130: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1140: 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20  TE_VERSION      
1150: 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65    "--VERS--".#de
1160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
1170: 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52  ION_NUMBER --VER
1180: 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64  SION-NUMBER--.#d
1190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55  efine SQLITE_SOU
11a0: 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53  RCE_ID      "--S
11b0: 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a  OURCE-ID--"../*.
11c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
11d0: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
11e0: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a  rsion Numbers.**
11f0: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
1200: 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69  e3_version, sqli
1210: 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a  te3_sourceid.**.
1220: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61  ** These interfa
1230: 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20  ces provide the 
1240: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
1250: 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   as the [SQLITE_
1260: 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51  VERSION],.** [SQ
1270: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1280: 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  BER], and [SQLIT
1290: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70  E_SOURCE_ID] C p
12a0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
12b0: 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73  os.** but are as
12c0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
12d0: 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61  e library instea
12e0: 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 20  d of the header 
12f0: 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75  file.  ^(Cautiou
1300: 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73  s.** programmers
1310: 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61   might include a
1320: 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e  ssert() statemen
1330: 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ts in their appl
1340: 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65  ication to.** ve
1350: 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73  rify that values
1360: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1370: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  se interfaces ma
1380: 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69  tch the macros i
1390: 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c  n.** the header,
13a0: 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72 65   and thus ensure
13b0: 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63   that the applic
13c0: 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70  ation is.** comp
13d0: 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69  iled with matchi
13e0: 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68  ng library and h
13f0: 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a  eader files..**.
1400: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1410: 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20  pre>.** assert( 
1420: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1430: 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c  on_number()==SQL
1440: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1450: 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  ER );.** assert(
1460: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1470: 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54  sourceid(),SQLIT
1480: 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20  E_SOURCE_ID)==0 
1490: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
14a0: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62  rcmp(sqlite3_lib
14b0: 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45  version(),SQLITE
14c0: 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a  _VERSION)==0 );.
14d0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
14e0: 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
14f0: 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  The sqlite3_vers
1500: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
1510: 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74  stant contains t
1520: 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49  he text of [SQLI
1530: 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d  TE_VERSION].** m
1540: 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69  acro.  ^The sqli
1550: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
1560: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1570: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
1580: 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c  he.** to the sql
1590: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
15a0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
15b0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62   The sqlite3_lib
15c0: 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e  version().** fun
15d0: 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65  ction is provide
15e0: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c  d for use in DLL
15f0: 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72  s since DLL user
1600: 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74  s usually do not
1610: 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20   have.** direct 
1620: 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67  access to string
1630: 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69   constants withi
1640: 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65  n the DLL.  ^The
1650: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  .** sqlite3_libv
1660: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20  ersion_number() 
1670: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1680: 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61   an integer equa
1690: 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  l to.** [SQLITE_
16a0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e  VERSION_NUMBER].
16b0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
16c0: 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69  ourceid() functi
16d0: 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61  on returns .** a
16e0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
16f0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68  ring constant wh
1700: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  ose value is the
1710: 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a   same as the .**
1720: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
1730: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
1740: 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  or macro..**.** 
1750: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
1760: 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64  e_version()] and
1770: 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f   [sqlite_source_
1780: 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  id()]..*/.SQLITE
1790: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
17a0: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
17b0: 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72  on[];.const char
17c0: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   *sqlite3_libver
17d0: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73  sion(void);.cons
17e0: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
17f0: 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a  sourceid(void);.
1800: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  int sqlite3_libv
1810: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f  ersion_number(vo
1820: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
1830: 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
1840: 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69  ibrary Compilati
1850: 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e  on Options Diagn
1860: 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ostics.**.** ^Th
1870: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1880: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66  eoption_used() f
1890: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
18a0: 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63  0 or 1 .** indic
18b0: 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74 68  ating whether th
18c0: 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74 69  e specified opti
18d0: 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20 61  on was defined a
18e0: 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69  t .** compile ti
18f0: 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45  me.  ^The SQLITE
1900: 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65 20  _ prefix may be 
1910: 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
1920: 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65   .** option name
1930: 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74   passed to sqlit
1940: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1950: 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a  _used().  .**.**
1960: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
1970: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1980: 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77  ) function allow
1990: 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f  s iterating.** o
19a0: 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20  ver the list of 
19b0: 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72  options that wer
19c0: 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d  e defined at com
19d0: 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20  pile time by.** 
19e0: 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d  returning the N-
19f0: 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20  th compile time 
1a00: 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20  option string.  
1a10: 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  ^If N is out of 
1a20: 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65  range,.** sqlite
1a30: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1a40: 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61 20  get() returns a 
1a50: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
1a60: 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20  The SQLITE_ .** 
1a70: 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65  prefix is omitte
1a80: 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e  d from any strin
1a90: 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a  gs returned by .
1aa0: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ** sqlite3_compi
1ab0: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a  leoption_get()..
1ac0: 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66  **.** ^Support f
1ad0: 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69  or the diagnosti
1ae0: 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69  c functions sqli
1af0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1b00: 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20  n_used().** and 
1b10: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1b20: 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20  ption_get() may 
1b30: 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70  be omitted by sp
1b40: 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a  ecifying the .**
1b50: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f   [SQLITE_OMIT_CO
1b60: 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47  MPILEOPTION_DIAG
1b70: 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d  S] option at com
1b80: 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  pile time..**.**
1b90: 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66   See also: SQL f
1ba0: 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65  unctions [sqlite
1bb0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
1bc0: 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1bd0: 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74  qlite_compileopt
1be0: 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74  ion_get()] and t
1bf0: 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69  he [compile_opti
1c00: 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a  ons pragma]..*/.
1c10: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
1c20: 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f  MIT_COMPILEOPTIO
1c30: 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73 71 6c 69  N_DIAGS.int sqli
1c40: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1c50: 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61  n_used(const cha
1c60: 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f  r *zOptName);.co
1c70: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1c80: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1c90: 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64  get(int N);.#end
1ca0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
1cb0: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
1cc0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
1cd0: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
1ce0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1cf0: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
1d00: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65  ction returns ze
1d10: 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  ro if and only i
1d20: 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20  f.** SQLite was 
1d30: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75  compiled with mu
1d40: 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74  texing code omit
1d50: 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a  ted due to the.*
1d60: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1d70: 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SAFE] compile-ti
1d80: 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20  me option being 
1d90: 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20  set to 0..**.** 
1da0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
1db0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
1dc0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
1dd0: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1de0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1df0: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1e00: 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c  macro is 1 or 2,
1e10: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
1e20: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1e30: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1e40: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1e50: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1e60: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1e70: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1e80: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1e90: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1ea0: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1eb0: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1ec0: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
1ed0: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
1ee0: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
1ef0: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
1f00: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
1f10: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
1f20: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1f30: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1f40: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1f50: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1f60: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1f70: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1f80: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1f90: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1fa0: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1fb0: 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1fc0: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20  behavior is for 
1fd0: 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e  mutexes to be en
1fe0: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  abled..**.** Thi
1ff0: 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
2000: 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70  be used by an ap
2010: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b  plication to mak
2020: 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  e sure that the.
2030: 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  ** version of SQ
2040: 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20  Lite that it is 
2050: 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20  linking against 
2060: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2070: 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64  h.** the desired
2080: 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20   setting of the 
2090: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
20a0: 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  FE] macro..**.**
20b0: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
20c0: 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20  only reports on 
20d0: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
20e0: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a   mutex setting.*
20f0: 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
2100: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61  _THREADSAFE] fla
2110: 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  g.  If SQLite is
2120: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
2130: 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  * SQLITE_THREADS
2140: 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e  AFE=1 or =2 then
2150: 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61   mutexes are ena
2160: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
2170: 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75  but.** can be fu
2180: 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79  lly or partially
2190: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
21a0: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
21b0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20  e3_config()].** 
21c0: 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b  with the verbs [
21d0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
21e0: 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51  NGLETHREAD], [SQ
21f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2200: 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20  ITHREAD],.** or 
2210: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
2220: 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54  ERIALIZED].  ^(T
2230: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2240: 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  of the.** sqlite
2250: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
2260: 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e  unction shows on
2270: 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  ly the compile-t
2280: 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a  ime setting of.*
2290: 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79 2c  * thread safety,
22a0: 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d   not any run-tim
22b0: 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61  e changes to tha
22c0: 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62  t setting made b
22d0: 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  y.** sqlite3_con
22e0: 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20  fig(). In other 
22f0: 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75 72  words, the retur
2300: 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
2310: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2320: 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65  ).** is unchange
2330: 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71  d by calls to sq
2340: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29  lite3_config().)
2350: 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20  ^.**.** See the 
2360: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
2370: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
2380: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
2390: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  formation..*/.in
23a0: 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  t sqlite3_thread
23b0: 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  safe(void);../*.
23c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
23d0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
23e0: 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f   Handle.** KEYWO
23f0: 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63  RDS: {database c
2400: 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61  onnection} {data
2410: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2420: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65  }.**.** Each ope
2430: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
2440: 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  e is represented
2450: 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   by a pointer to
2460: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a   an instance of.
2470: 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74  ** the opaque st
2480: 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73  ructure named "s
2490: 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20  qlite3".  It is 
24a0: 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20  useful to think 
24b0: 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a  of an sqlite3.**
24c0: 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f   pointer as an o
24d0: 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c  bject.  The [sql
24e0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
24f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2500: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2510: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
2520: 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20  erfaces are its 
2530: 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e  constructors, an
2540: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2550: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
2560: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20  te3_close_v2()] 
2570: 61 72 65 20 69 74 73 20 64 65 73 74 72 75 63 74  are its destruct
2580: 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72 65 20  ors.  There are 
2590: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e  many other.** in
25a0: 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61  terfaces (such a
25b0: 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  s.** [sqlite3_pr
25c0: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
25d0: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
25e0: 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a  ction()], and.**
25f0: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
2600: 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d  imeout()] to nam
2610: 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61  e but three) tha
2620: 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e  t are methods on
2630: 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f   an.** sqlite3 o
2640: 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65  bject..*/.typede
2650: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2660: 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a   sqlite3;../*.**
2670: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69   CAPI3REF: 64-Bi
2680: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a  t Integer Types.
2690: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
26a0: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
26b0: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65  _uint64.**.** Be
26c0: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e  cause there is n
26d0: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d  o cross-platform
26e0: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20   way to specify 
26f0: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74  64-bit integer t
2700: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ypes.** SQLite i
2710: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73  ncludes typedefs
2720: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e   for 64-bit sign
2730: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20  ed and unsigned 
2740: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  integers..**.** 
2750: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  The sqlite3_int6
2760: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69  4 and sqlite3_ui
2770: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65  nt64 are the pre
2780: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69  ferred type defi
2790: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20  nitions..** The 
27a0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64  sqlite_int64 and
27b0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
27c0: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74  ypes are support
27d0: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
27e0: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
27f0: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y only..**.** ^T
2800: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  he sqlite3_int64
2810: 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36   and sqlite_int6
2820: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2830: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2840: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32  .** between -922
2850: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 38  3372036854775808
2860: 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36   and +9223372036
2870: 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73  854775807 inclus
2880: 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ive.  ^The.** sq
2890: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64  lite3_uint64 and
28a0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
28b0: 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69  ypes can store i
28c0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a  nteger values .*
28d0: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
28e0: 2b 31 38 34 34 36 37 34 34 30 37 33 37 30 39 35  +184467440737095
28f0: 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e  51615 inclusive.
2900: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
2910: 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74  E_INT64_TYPE.  t
2920: 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  ypedef SQLITE_IN
2930: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
2940: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
2950: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45   unsigned SQLITE
2960: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2970: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66  te_uint64;.#elif
2980: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45   defined(_MSC_VE
2990: 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f  R) || defined(__
29a0: 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79  BORLANDC__).  ty
29b0: 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71  pedef __int64 sq
29c0: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
29d0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f  pedef unsigned _
29e0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
29f0: 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79  nt64;.#else.  ty
2a00: 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20  pedef long long 
2a10: 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  int sqlite_int64
2a20: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2a30: 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69  gned long long i
2a40: 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nt sqlite_uint64
2a50: 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66  ;.#endif.typedef
2a60: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2a70: 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70  lite3_int64;.typ
2a80: 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74  edef sqlite_uint
2a90: 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  64 sqlite3_uint6
2aa0: 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d  4;../*.** If com
2ab0: 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f  piling for a pro
2ac0: 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b  cessor that lack
2ad0: 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  s floating point
2ae0: 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62   support,.** sub
2af0: 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20  stitute integer 
2b00: 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69  for floating-poi
2b10: 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  nt..*/.#ifdef SQ
2b20: 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49  LITE_OMIT_FLOATI
2b30: 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e  NG_POINT.# defin
2b40: 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  e double sqlite3
2b50: 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f  _int64.#endif../
2b60: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2b70: 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73  losing A Databas
2b80: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e Connection.** 
2b90: 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  DESTRUCTOR: sqli
2ba0: 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
2bb0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2bc0: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2bd0: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2be0: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2bf0: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2c00: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2c10: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2c20: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2c30: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2c40: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2c50: 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71  K] if.** the [sq
2c60: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73  lite3] object is
2c70: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2c80: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2c90: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65  associated.** re
2ca0: 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c  sources are deal
2cb0: 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  located..**.** ^
2cc0: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
2cd0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73  connection is as
2ce0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e  sociated with un
2cf0: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72  finalized prepar
2d00: 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  ed.** statements
2d10: 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73   or unfinished s
2d20: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62  qlite3_backup ob
2d30: 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74  jects then sqlit
2d40: 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69  e3_close().** wi
2d50: 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74  ll leave the dat
2d60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d70: 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e   open and return
2d80: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
2d90: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
2da0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
2db0: 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  led with unfinal
2dc0: 69 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74  ized prepared st
2dd0: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f  atements.** and/
2de0: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
2df0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74  lite3_backups, t
2e00: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2e10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f   connection beco
2e20: 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62  mes.** an unusab
2e30: 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63  le "zombie" whic
2e40: 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  h will automatic
2e50: 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61  ally be dealloca
2e60: 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  ted when the.** 
2e70: 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74  last prepared st
2e80: 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c  atement is final
2e90: 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74  ized or the last
2ea0: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2eb0: 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20  is.** finished. 
2ec0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f   The sqlite3_clo
2ed0: 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  se_v2() interfac
2ee0: 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  e is intended fo
2ef0: 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f  r use with.** ho
2f00: 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61  st languages tha
2f10: 74 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f  t are garbage co
2f20: 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65  llected, and whe
2f30: 72 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20  re the order in 
2f40: 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63  which.** destruc
2f50: 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20  tors are called 
2f60: 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a  is arbitrary..**
2f70: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
2f80: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33   should [sqlite3
2f90: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2fa0: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61  lize] all [prepa
2fb0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2fc0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2fd0: 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d  b_close | close]
2fe0: 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   all [BLOB handl
2ff0: 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  es], and .** [sq
3000: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e  lite3_backup_fin
3010: 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c  ish | finish] al
3020: 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  l [sqlite3_backu
3030: 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63  p] objects assoc
3040: 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
3050: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
3060: 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65  ct prior to atte
3070: 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20  mpting to close 
3080: 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66  the object.  ^If
3090: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  .** sqlite3_clos
30a0: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
30b0: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
30c0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
30d0: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
30e0: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
30f0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
3100: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
3110: 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69   and/or.** [sqli
3120: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
3130: 63 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75  cts then it retu
3140: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
3150: 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61  and the dealloca
3160: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75  tion.** of resou
3170: 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64  rces is deferred
3180: 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70   until all [prep
3190: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
31a0: 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  , [BLOB handles]
31b0: 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ,.** and [sqlite
31c0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31d0: 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72  s are also destr
31e0: 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  oyed..**.** ^If 
31f0: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
3200: 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64  ect is destroyed
3210: 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63   while a transac
3220: 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a  tion is open,.**
3230: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
3240: 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
3250: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
3260: 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d  *.** The C param
3270: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3280: 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b  _close(C)] and [
3290: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
32a0: 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  (C)].** must be 
32b0: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a  either a NULL.**
32c0: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b   pointer or an [
32d0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
32e0: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
32f0: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3300: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
3310: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
3320: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
3330: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f  en_v2()], and no
3340: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f  t previously clo
3350: 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  sed..** ^Calling
3360: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
3370: 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   or sqlite3_clos
3380: 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55  e_v2() with a NU
3390: 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72  LL pointer.** ar
33a0: 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d  gument is a harm
33b0: 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69  less no-op..*/.i
33c0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
33d0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20  (sqlite3*);.int 
33e0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
33f0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
3400: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
3410: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
3420: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
3430: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
3440: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
3450: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
3460: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
3470: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
3480: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
3490: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
34a0: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
34b0: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
34c0: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
34d0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
34e0: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
34f0: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
3500: 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
3510: 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
3520: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
3530: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
3540: 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61  nience wrapper a
3550: 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
3560: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
3570: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
3580: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
3590: 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20  finalize()],.** 
35a0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61  that allows an a
35b0: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75  pplication to ru
35c0: 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65  n multiple state
35d0: 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20  ments of SQL.** 
35e0: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
35f0: 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43  o use a lot of C
3600: 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54   code. .**.** ^T
3610: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3620: 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73  ) interface runs
3630: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54   zero or more UT
3640: 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20  F-8 encoded,.** 
3650: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
3660: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
3670: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74  s passed into it
3680: 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a  s 2nd argument,.
3690: 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78  ** in the contex
36a0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
36b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
36c0: 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20  assed in as its 
36d0: 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  1st.** argument.
36e0: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
36f0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74  ck function of t
3700: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
3710: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
3720: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ec() is not NULL
3730: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76  , then it is inv
3740: 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65  oked for each re
3750: 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69  sult row.** comi
3760: 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76  ng out of the ev
3770: 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74  aluated SQL stat
3780: 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74  ements.  ^The 4t
3790: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  h argument to.**
37a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
37b0: 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75  is relayed throu
37c0: 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72  gh to the 1st ar
37d0: 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a  gument of each.*
37e0: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63  * callback invoc
37f0: 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20  ation.  ^If the 
3800: 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72  callback pointer
3810: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3820: 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74  ().** is NULL, t
3830: 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20  hen no callback 
3840: 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20  is ever invoked 
3850: 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20  and result rows 
3860: 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a  are.** ignored..
3870: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  **.** ^If an err
3880: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
3890: 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53  evaluating the S
38a0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61  QL statements pa
38b0: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  ssed into.** sql
38c0: 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65  ite3_exec(), the
38d0: 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  n execution of t
38e0: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
38f0: 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a  ment stops and.*
3900: 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61  * subsequent sta
3910: 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70  tements are skip
3920: 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74  ped.  ^If the 5t
3930: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3940: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3950: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
3960: 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73  n any error mess
3970: 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69  age is written i
3980: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
3990: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
39a0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
39b0: 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74  nd passed back t
39c0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
39d0: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20  arameter..** To 
39e0: 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61  avoid memory lea
39f0: 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ks, the applicat
3a00: 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b  ion should invok
3a10: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
3a20: 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d  )].** on error m
3a30: 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72  essage strings r
3a40: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
3a50: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3a60: 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r of.** sqlite3_
3a70: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
3a80: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3a90: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
3aa0: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
3ab0: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3ac0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3ad0: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
3ae0: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
3af0: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
3b00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
3b10: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
3b20: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
3b30: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
3b40: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
3b50: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
3b60: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3b70: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
3b80: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
3b90: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
3ba0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
3bb0: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
3bc0: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
3bd0: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
3be0: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
3bf0: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
3c00: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
3c10: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
3c20: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
3c30: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3c40: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
3c50: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
3c60: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
3c70: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
3c80: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
3c90: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3ca0: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
3cb0: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
3cc0: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3cd0: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
3ce0: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
3cf0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3d00: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
3d10: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
3d20: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
3d30: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
3d40: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
3d50: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
3d60: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
3d70: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
3d80: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3d90: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3da0: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
3db0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
3dc0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3dd0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3de0: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3df0: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
3e00: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
3e10: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
3e20: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
3e30: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
3e40: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
3e50: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3e60: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
3e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
3e80: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
3e90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3ea0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
3eb0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
3ec0: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
3ed0: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
3ee0: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
3ef0: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
3f00: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
3f10: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
3f20: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
3f30: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
3f40: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
3f50: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
3f60: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
3f70: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
3f80: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3f90: 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72  ation must ensur
3fa0: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
3fb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3fc0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
3fd0: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
3fe0: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
3ff0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
4000: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
4010: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
4020: 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61  lose the [databa
4030: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
4040: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
4050: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61      the 1st para
4060: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
4070: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
4080: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
4090: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e  running..** <li>
40a0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
40b0: 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79   must not modify
40c0: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
40d0: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69  nt text passed i
40e0: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  nto.**      the 
40f0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
4100: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4110: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
4120: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
4130: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ul>.*/.int
4140: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
4150: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4170: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
4180: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
4190: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
41a0: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
41b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41c0: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
41d0: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
41e0: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
41f0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
4200: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
4210: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
4220: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
4230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4240: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
4250: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
4260: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
4270: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
4280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4290: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
42a0: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
42b0: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
42c0: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
42d0: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
42e0: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20  S: {result code 
42f0: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4300: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
4310: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
4320: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
4330: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
4340: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
4350: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
4360: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f  dicate success o
4370: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
4380: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
4390: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
43a0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
43b0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
43c0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74  * See also: [ext
43d0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
43e0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a  e definitions].*
43f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4400: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
4410: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
4420: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
4430: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
4440: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
4450: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
4460: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
4470: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
4480: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
4490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
44a0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
44b0: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
44c0: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
44d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44e0: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
44f0: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
4500: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
4510: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4520: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
4530: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
4540: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
4550: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
4560: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
4570: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
4580: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4590: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
45a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
45b0: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
45c0: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
45d0: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
45e0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
45f0: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4600: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4610: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4620: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4630: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4640: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
4650: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
4660: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
4670: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
4680: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4690: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
46a0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
46b0: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
46c0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
46d0: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
46e0: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
46f0: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4700: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4710: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4720: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4730: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4740: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
4750: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4760: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
4770: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
4780: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4790: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
47a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
47b0: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
47c0: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
47d0: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
47e0: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
47f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4800: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
4810: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
4820: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
4830: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4840: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
4850: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
4860: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
4870: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4880: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4890: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
48a0: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
48b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
48c0: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
48d0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
48e0: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
48f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4900: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
4910: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
4920: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
4930: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
4940: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
4950: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
4960: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
4970: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
4980: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4990: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
49a0: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
49b0: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
49c0: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
49d0: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
49e0: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
49f0: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4a00: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
4a10: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
4a20: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
4a30: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
4a40: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
4a50: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
4a60: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
4a70: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
4a80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4a90: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4aa0: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4ab0: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4ac0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4ad0: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4ae0: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4af0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4b00: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4b10: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4b20: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4b30: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4b40: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4b50: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4b60: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4b70: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4b80: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4b90: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4ba0: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4bc0: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4bd0: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4be0: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4c00: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4c10: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4c20: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4c30: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4c40: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4c50: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4c60: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4c70: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4c80: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4c90: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4ca0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4cb0: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4cc0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4cd0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4ce0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4cf0: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4d00: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4d10: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4d20: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4d30: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4d40: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4d50: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4d60: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4d70: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4d80: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4d90: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4da0: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4db0: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4dc0: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4dd0: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4de0: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4df0: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4e00: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4e10: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4e20: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4e30: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4e40: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4e50: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20  .3.8 and later) 
4e60: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4e70: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4e80: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4e90: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4ea0: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4eb0: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4ec0: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
4ed0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4ee0: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
4ef0: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4f00: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4f10: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4f20: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4f30: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4f40: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4f50: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
4f60: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
4f70: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
4f80: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
4f90: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
4fa0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4fb0: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
4fc0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4fd0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4fe0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4ff0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5000: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5010: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5020: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5030: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5040: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5050: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5060: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5070: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5080: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5090: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
50a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50b0: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
50c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50d0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
50e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50f0: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5100: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5110: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5120: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5130: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5140: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5150: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5160: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5170: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5180: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5190: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
51a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51b0: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
51c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
51d0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
51e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51f0: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5200: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5210: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5220: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5230: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5240: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5250: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5260: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5270: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5280: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5290: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
52a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52b0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
52c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52d0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
52e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52f0: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5300: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5310: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5320: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5330: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5340: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5350: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5360: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5370: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5380: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5390: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
53a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53b0: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
53c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53d0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
53e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53f0: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5400: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5410: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5420: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5430: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5440: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5450: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5460: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5470: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5480: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5490: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
54a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54b0: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
54c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54d0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
54e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54f0: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5500: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5510: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5520: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5530: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5540: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5550: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5560: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5570: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5580: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5590: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
55a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55b0: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
55c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55d0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
55e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55f0: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5600: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5610: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5620: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5630: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5650: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5660: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5670: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
5680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5690: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
56a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56b0: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
56c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
56d0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
56e0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
56f0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5710: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5720: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5730: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5740: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5750: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5760: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5770: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5780: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5790: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
57a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
57b0: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
57c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
57d0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
57e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
57f0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5800: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5810: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5820: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5830: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5840: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5850: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5860: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5870: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5880: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5890: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
58a0: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
58b0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
58c0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
58d0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
58e0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
58f0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5900: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5910: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5920: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5930: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5940: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5950: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5960: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5970: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5980: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5990: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
59a0: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
59b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
59c0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
59d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
59e0: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
59f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
5a00: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5a10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5a20: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5a30: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5a40: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5a50: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a60: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5a70: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5a80: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5a90: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5aa0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ab0: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
5ac0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ad0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5ae0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5af0: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
5b00: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5b10: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5b20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5b30: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5b40: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5b50: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5b60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5b70: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5b80: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5b90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5ba0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5bb0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5bc0: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
5bd0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5be0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
5bf0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5c00: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5c10: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5c20: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5c30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5c40: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5c50: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5c60: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5c70: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5c80: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5c90: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5ca0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5cb0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5cc0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5cd0: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5ce0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5cf0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5d10: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5d20: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5d30: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5d40: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5d50: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5d60: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5d70: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5d80: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
5d90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
5da0: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
5db0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5dc0: 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52  LITE_OK_LOAD_PER
5dd0: 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53 51  MANENTLY     (SQ
5de0: 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29  LITE_OK | (1<<8)
5df0: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5e00: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5e10: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5e20: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5e30: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5e40: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5e50: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5e60: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5e70: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5e80: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
5e90: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
5ea0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5eb0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
5ec0: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
5ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5ee0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5ef0: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5f00: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5f10: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f30: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5f40: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5f50: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5f60: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5f70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f80: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
5f90: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
5fa0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5fb0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5fc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5fd0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
5fe0: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
5ff0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6010: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
6020: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
6030: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6050: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
6060: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
6070: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6080: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6090: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
60a0: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
60b0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
60c0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
60d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60e0: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
60f0: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
6100: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6110: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6120: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6130: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
6140: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
6150: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6170: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
6180: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
6190: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61b0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
61c0: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
61d0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61f0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
6200: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
6210: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6220: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6230: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
6240: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
6250: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6260: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6270: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
6280: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
6290: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62b0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
62c0: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
62d0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62f0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
6300: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
6310: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6320: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6340: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
6350: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
6360: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6370: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6380: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6390: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
63a0: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
63b0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
63c0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
63d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
63e0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
63f0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
6400: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6410: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6430: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
6440: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
6450: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
6460: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
6470: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6480: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
6490: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
64a0: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
64b0: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
64c0: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
64d0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
64e0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
64f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
6500: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
6510: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
6520: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
6530: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
6540: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
6550: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
6560: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
6570: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
6580: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
6590: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
65a0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
65b0: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
65c0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
65d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
65e0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
65f0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
6600: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
6610: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
6620: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6630: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
6640: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
6650: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
6660: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
6670: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
6680: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
6690: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
66a0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
66b0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
66c0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
66d0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
66e0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
66f0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
6700: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
6710: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
6720: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
6730: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
6740: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
6750: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
6760: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
6770: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
6780: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6790: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
67a0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
67b0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
67c0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
67d0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
67e0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
67f0: 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68  to xWrite().  Th
6800: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
6810: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
6820: 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  TE property mean
6830: 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20  s that.** after 
6840: 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67  reboot following
6850: 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65   a crash or powe
6860: 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79  r loss, the only
6870: 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66   bytes in a.** f
6880: 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72  ile that were wr
6890: 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70  itten at the app
68a0: 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d  lication level m
68b0: 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65  ight have change
68c0: 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64  d.** and that ad
68d0: 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76  jacent bytes, ev
68e0: 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20  en bytes within 
68f0: 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20  the same sector 
6900: 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  are.** guarantee
6910: 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65  d to be unchange
6920: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
6930: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
6940: 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c  _WHEN_OPEN.** fl
6950: 61 67 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  ag indicate that
6960: 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62   a file cannot b
6970: 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 6f  e deleted when o
6980: 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c  pen.  The.** SQL
6990: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
69a0: 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61 74  BLE flag indicat
69b0: 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c 65  es that the file
69c0: 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f   is on.** read-o
69d0: 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63 61  nly media and ca
69e0: 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
69f0: 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73 65  even by processe
6a00: 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74  s with.** elevat
6a10: 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a  ed privileges..*
6a20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6a30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20  _IOCAP_ATOMIC   
6a40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6a50: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
6a60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6a70: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20  OMIC512         
6a80: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
6a90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6aa0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
6ab0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6ac0: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
6ad0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6ae0: 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC2K            
6af0: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
6b00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6b10: 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20  AP_ATOMIC4K     
6b20: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6b30: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
6b40: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6b50: 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  8K              
6b60: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
6b70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6b80: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
6b90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6ba0: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
6bb0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
6bc0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6bd0: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e  x00000080.#defin
6be0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6bf0: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20  TOMIC64K        
6c00: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
6c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6c20: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
6c30: 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30  D            0x0
6c40: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
6c50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6c60: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20  UENTIAL         
6c70: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23      0x00000400.#
6c80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6c90: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
6ca0: 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30  WHEN_OPEN  0x000
6cb0: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
6cc0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
6cd0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
6ce0: 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65    0x00001000.#de
6cf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6d00: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20  P_IMMUTABLE     
6d10: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32           0x00002
6d20: 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  000../*.** CAPI3
6d30: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
6d40: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
6d50: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
6d60: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
6d70: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6d80: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
6d90: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
6da0: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
6db0: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
6dc0: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
6dd0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6de0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
6df0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6e00: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
6e10: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
6e20: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
6e30: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
6e40: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
6e50: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
6e60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6e70: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
6e80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6e90: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
6ea0: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
6eb0: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
6ec0: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
6ed0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
6ee0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
6ef0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
6f00: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6f10: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6f20: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
6f30: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
6f40: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6f50: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6f60: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
6f70: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
6f80: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6f90: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
6fa0: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
6fb0: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
6fc0: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
6fd0: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
6fe0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
6ff0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
7000: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
7010: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
7020: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
7030: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
7040: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
7050: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
7060: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
7070: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
7080: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
7090: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
70a0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
70b0: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
70c0: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
70d0: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
70e0: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
70f0: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
7100: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
7110: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7120: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
7130: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
7140: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
7150: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
7160: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
7170: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
7180: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
7190: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
71a0: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
71b0: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
71c0: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
71d0: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
71e0: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
71f0: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
7200: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
7210: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
7220: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
7230: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
7240: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
7250: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
7260: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
7270: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
7280: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
7290: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
72a0: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
72b0: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
72c0: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
72d0: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
72e0: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
72f0: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
7300: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
7310: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
7320: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
7330: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
7340: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
7350: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
7360: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
7370: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
7380: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
7390: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
73a0: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
73b0: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
73c0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
73d0: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
73e0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
73f0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
7400: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
7410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7420: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
7430: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
7440: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7450: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
7460: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
7470: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
7480: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
7490: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
74a0: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
74b0: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
74c0: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
74d0: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
74e0: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
74f0: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
7500: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
7510: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
7520: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
7530: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
7540: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
7550: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
7560: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
7570: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
7580: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7590: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
75a0: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
75b0: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
75c0: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
75d0: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
75e0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
75f0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
7600: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
7610: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
7620: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
7630: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
7640: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
7650: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
7660: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
7670: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
7680: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
7690: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
76a0: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
76b0: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
76c0: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
76d0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
76e0: 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  n] method popula
76f0: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
7700: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
7710: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
7720: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
7730: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
7740: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
7750: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
7760: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
7770: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
7780: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
7790: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
77a0: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
77b0: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
77c0: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
77d0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
77e0: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
77f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7800: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
7810: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7820: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73  .xOpen] method s
7830: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
7840: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7850: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
7860: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
7870: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
7880: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
7890: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
78a0: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
78b0: 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n if the [sqlite
78c0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70  3_vfs.xOpen] rep
78d0: 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61  orted that it fa
78e0: 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e  iled.  The.** on
78f0: 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e  ly way to preven
7900: 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f  t a call to xClo
7910: 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  se following a f
7920: 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76  ailed [sqlite3_v
7930: 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20  fs.xOpen].** is 
7940: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
7950: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73  _vfs.xOpen] to s
7960: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
7970: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
7980: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e  ment.** to NULL.
7990: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
79a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
79b0: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
79c0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
79d0: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
79e0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
79f0: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
7a00: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
7a10: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
7a20: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
7a30: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
7a40: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
7a50: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
7a60: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
7a70: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
7a80: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
7a90: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
7aa0: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
7ab0: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
7ac0: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
7ad0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
7ae0: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
7af0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
7b00: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
7b10: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
7b20: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
7b30: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
7b40: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
7b50: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7b60: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
7b70: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7b80: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
7b90: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
7ba0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7bb0: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
7bc0: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
7bd0: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
7be0: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
7bf0: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
7c00: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
7c10: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
7c20: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
7c30: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
7c40: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
7c50: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
7c60: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
7c70: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
7c80: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
7c90: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
7ca0: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
7cb0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
7cc0: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
7cd0: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
7ce0: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
7cf0: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
7d00: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
7d10: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
7d20: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
7d30: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
7d40: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
7d50: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
7d60: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
7d70: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
7d80: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
7d90: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7da0: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
7db0: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
7dc0: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
7dd0: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
7de0: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
7df0: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
7e00: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
7e10: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
7e20: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
7e30: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
7e40: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
7e50: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
7e60: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
7e70: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
7e80: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
7e90: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
7ea0: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
7eb0: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
7ec0: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
7ed0: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
7ee0: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
7ef0: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
7f00: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
7f10: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
7f20: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
7f30: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
7f40: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
7f50: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
7f60: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
7f70: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
7f80: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
7f90: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
7fa0: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66  own use..** A [f
7fb0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
7fc0: 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70  des | list of op
7fd0: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e  codes] less than
7fe0: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c   100 is availabl
7ff0: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
8000: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  ns that define a
8010: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e   custom xFileCon
8020: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75  trol method shou
8030: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a  ld use opcodes.*
8040: 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  * greater than 1
8050: 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66  00 to avoid conf
8060: 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c  licts.  VFS impl
8070: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
8080: 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
8090: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66  LITE_NOTFOUND] f
80a0: 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  or file control 
80b0: 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65  opcodes that the
80c0: 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f  y do not.** reco
80d0: 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  gnize..**.** The
80e0: 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d   xSectorSize() m
80f0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68  ethod returns th
8100: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66  e sector size of
8110: 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74   the.** device t
8120: 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68  hat underlies th
8130: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63  e file.  The sec
8140: 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a  tor size is the.
8150: 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65  ** minimum write
8160: 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72   that can be per
8170: 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64  formed without d
8180: 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68  isturbing.** oth
8190: 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  er bytes in the 
81a0: 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69  file.  The xDevi
81b0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
81c0: 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  s().** method re
81d0: 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74  turns a bit vect
81e0: 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65  or describing be
81f0: 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a  haviors of the.*
8200: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76  * underlying dev
8210: 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ice:.**.** <ul>.
8220: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8230: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  IOCAP_ATOMIC].**
8240: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8250: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a  CAP_ATOMIC512].*
8260: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8270: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a  OCAP_ATOMIC1K].*
8280: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8290: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a  OCAP_ATOMIC2K].*
82a0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
82b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a  OCAP_ATOMIC4K].*
82c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
82d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a  OCAP_ATOMIC8K].*
82e0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
82f0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a  OCAP_ATOMIC16K].
8300: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8310: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d  IOCAP_ATOMIC32K]
8320: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8330: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
8340: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8350: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
8360: 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  END].** <li> [SQ
8370: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8380: 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  NTIAL].** </ul>.
8390: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
83a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
83b0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
83c0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
83d0: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
83e0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
83f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8400: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
8410: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
8420: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
8430: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
8440: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
8450: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
8460: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
8470: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
8480: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
8490: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
84a0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
84b0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
84c0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
84d0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
84e0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
84f0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
8500: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
8510: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
8520: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
8530: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
8540: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
8550: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8560: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
8570: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
8580: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
8590: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
85a0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
85b0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
85c0: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a  to xWrite()..**.
85d0: 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65  ** If xRead() re
85e0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45  turns SQLITE_IOE
85f0: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74  RR_SHORT_READ it
8600: 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a   must also fill.
8610: 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64  ** in the unread
8620: 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65   portions of the
8630: 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72   buffer with zer
8640: 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a  os.  A VFS that.
8650: 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f  ** fails to zero
8660: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
8670: 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20  s might seem to 
8680: 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a  work.  However,.
8690: 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65  ** failure to ze
86a0: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
86b0: 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61  ads will eventua
86c0: 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64  lly lead to.** d
86d0: 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
86e0: 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
86f0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
8700: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
8710: 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  _io_methods;.str
8720: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
8730: 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69  ethods {.  int i
8740: 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
8750: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
8760: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8770: 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f  *xRead)(sqlite3_
8780: 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e  file*, void*, in
8790: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
87a0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
87b0: 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71  int (*xWrite)(sq
87c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e  lite3_file*, con
87d0: 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  st void*, int iA
87e0: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
87f0: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
8800: 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c  (*xTruncate)(sql
8810: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8820: 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b  te3_int64 size);
8830: 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28  .  int (*xSync)(
8840: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8850: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74  nt flags);.  int
8860: 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71   (*xFileSize)(sq
8870: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8880: 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a  ite3_int64 *pSiz
8890: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63  e);.  int (*xLoc
88a0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
88b0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
88c0: 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33  xUnlock)(sqlite3
88d0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
88e0: 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65  int (*xCheckRese
88f0: 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65  rvedLock)(sqlite
8900: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52  3_file*, int *pR
8910: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
8920: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71  xFileControl)(sq
8930: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8940: 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29   op, void *pArg)
8950: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f  ;.  int (*xSecto
8960: 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  rSize)(sqlite3_f
8970: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8980: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
8990: 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66  stics)(sqlite3_f
89a0: 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  ile*);.  /* Meth
89b0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
89c0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
89d0: 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68  1 */.  int (*xSh
89e0: 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  mMap)(sqlite3_fi
89f0: 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e  le*, int iPg, in
8a00: 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69  t pgsz, int, voi
8a10: 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20  d volatile**);. 
8a20: 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29   int (*xShmLock)
8a30: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8a40: 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20  int offset, int 
8a50: 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  n, int flags);. 
8a60: 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72   void (*xShmBarr
8a70: 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ier)(sqlite3_fil
8a80: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  e*);.  int (*xSh
8a90: 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f  mUnmap)(sqlite3_
8aa0: 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74  file*, int delet
8ab0: 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74  eFlag);.  /* Met
8ac0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
8ad0: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
8ae0: 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46   2 */.  int (*xF
8af0: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
8b00: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8b10: 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41  64 iOfst, int iA
8b20: 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a  mt, void **pp);.
8b30: 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68    int (*xUnfetch
8b40: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8b50: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8b60: 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a  Ofst, void *p);.
8b70: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
8b80: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
8b90: 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20   version 3 */.  
8ba0: 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  /* Additional me
8bb0: 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64  thods may be add
8bc0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
8bd0: 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  eases */.};../*.
8be0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61  ** CAPI3REF: Sta
8bf0: 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72  ndard File Contr
8c00: 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45  ol Opcodes.** KE
8c10: 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f  YWORDS: {file co
8c20: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b  ntrol opcodes} {
8c30: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
8c40: 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ode}.**.** These
8c50: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
8c60: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
8c70: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
8c80: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
8c90: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
8ca0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8cb0: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
8cc0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
8cd0: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
8ce0: 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ce..**.** <ul>.*
8cf0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8d00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d  CNTL_LOCKSTATE]]
8d10: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8d20: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
8d30: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8d40: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
8d50: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
8d60: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
8d70: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
8d80: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
8d90: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
8da0: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
8db0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
8dc0: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
8dd0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
8de0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
8df0: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
8e00: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
8e10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
8e20: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
8e30: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
8e40: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
8e50: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
8e60: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
8e70: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
8e80: 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e  esting and is on
8e90: 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65  ly available whe
8ea0: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53  n the SQLITE_TES
8eb0: 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  T.** compile-tim
8ec0: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  e option is used
8ed0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
8ee0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
8ef0: 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  HINT]].** The [S
8f00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
8f10: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
8f20: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
8f30: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
8f40: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
8f50: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
8f60: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
8f70: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
8f80: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
8f90: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
8fa0: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
8fb0: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
8fc0: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
8fd0: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
8fe0: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
8ff0: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
9000: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
9010: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
9020: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
9030: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
9040: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
9050: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
9060: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
9070: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
9080: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9090: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
90a0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
90b0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
90c0: 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  IZE] opcode is u
90d0: 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74  sed to request t
90e0: 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65  hat the VFS.** e
90f0: 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63  xtends and trunc
9100: 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ates the databas
9110: 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73  e file in chunks
9120: 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69   of a size speci
9130: 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75  fied.** by the u
9140: 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ser. The fourth 
9150: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
9160: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9170: 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  l()] should .** 
9180: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65  point to an inte
9190: 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63  ger (type int) c
91a0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65  ontaining the ne
91b0: 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20  w chunk-size to 
91c0: 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e  use.** for the n
91d0: 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73  ominated databas
91e0: 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61  e. Allocating da
91f0: 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63  tabase file spac
9200: 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68  e in large.** ch
9210: 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74  unks (say 1MB at
9220: 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65   a time), may re
9230: 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d  duce file-system
9240: 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61   fragmentation a
9250: 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65  nd.** improve pe
9260: 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d  rformance on som
9270: 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a  e systems..**.**
9280: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9290: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
92a0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
92b0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
92c0: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
92d0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
92e0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
92f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9300: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
9310: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
9320: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
9330: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
9340: 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f  ee also [SQLITE_
9350: 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f  FCNTL_JOURNAL_PO
9360: 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  INTER]..**.** <l
9370: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9380: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
9390: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
93a0: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
93b0: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
93c0: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
93d0: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
93e0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
93f0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
9400: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
9410: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69  journal file (ei
9420: 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c  ther.** the [rol
9430: 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f  lback journal] o
9440: 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65  r the [write-ahe
9450: 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70  ad log]) for a p
9460: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
9470: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
9480: 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c  .  See also [SQL
9490: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
94a0: 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  OINTER]..**.** <
94b0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
94c0: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d  L_SYNC_OMITTED]]
94d0: 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e  .** No longer in
94e0: 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e   use..**.** <li>
94f0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
9500: 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  YNC]].** The [SQ
9510: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d  LITE_FCNTL_SYNC]
9520: 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72   opcode is gener
9530: 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ated internally 
9540: 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a  by SQLite and.**
9550: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53   sent to the VFS
9560: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66   immediately bef
9570: 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65  ore the xSync me
9580: 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
9590: 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65  on a.** database
95a0: 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72   file descriptor
95b0: 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79  . Or, if the xSy
95c0: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74  nc method is not
95d0: 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63   invoked .** bec
95e0: 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61  ause the user ha
95f0: 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c  s configured SQL
9600: 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52  ite with .** [PR
9610: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
9620: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
9630: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73  onous=OFF] it is
9640: 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63   invoked in plac
9650: 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79  e .** of the xSy
9660: 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f  nc method. In mo
9670: 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f  st cases, the po
9680: 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70  inter argument p
9690: 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  assed with.** th
96a0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
96b0: 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72  is NULL. However
96c0: 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73  , if the databas
96d0: 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20  e file is being 
96e0: 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72  synced.** as par
96f0: 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74  t of a multi-dat
9700: 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68  abase commit, th
9710: 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  e argument point
9720: 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69  s to a nul-termi
9730: 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
9740: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74  containing the t
9750: 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74  ransactions mast
9760: 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20  er-journal file 
9770: 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74  name. VFSes that
9780: 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64   .** do not need
9790: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f   this signal sho
97a0: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
97b0: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
97c0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a   Applications .*
97d0: 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  * should not cal
97e0: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  l [sqlite3_file_
97f0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
9800: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
9810: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20  oing so may .** 
9820: 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72  disrupt the oper
9830: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
9840: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
9850: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
9860: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
9870: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
9880: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a  MMIT_PHASETWO]].
9890: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
98a0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
98b0: 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20  ETWO] opcode is 
98c0: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
98d0: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a  ally by SQLite.*
98e0: 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68  * and sent to th
98f0: 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72  e VFS after a tr
9900: 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65  ansaction has be
9910: 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d  en committed imm
9920: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20  ediately.** but 
9930: 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62  before the datab
9940: 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e  ase is unlocked.
9950: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e   VFSes that do n
9960: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
9970: 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69  nal.** should si
9980: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
9990: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
99a0: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
99b0: 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  ot call.** [sqli
99c0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
99d0: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
99e0: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
99f0: 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65   may disrupt the
9a00: 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f   .** operation o
9a10: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
9a20: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
9a30: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
9a40: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9a50: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9a60: 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20  RETRY]].** ^The 
9a70: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
9a80: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70  N32_AV_RETRY] op
9a90: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9aa0: 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61  configure automa
9ab0: 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75  tic.** retry cou
9ac0: 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c  nts and interval
9ad0: 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69  s for certain di
9ae0: 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  sk I/O operation
9af0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e  s for the.** win
9b00: 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72  dows [VFS] in or
9b10: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72  der to provide r
9b20: 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65  obustness in the
9b30: 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20   presence of.** 
9b40: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
9b50: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
9b60: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
9b70: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
9b80: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
9b90: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
9ba0: 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e  delete operation
9bb0: 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73  s up to 10 times
9bc0: 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a  , with a delay.*
9bd0: 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63  * of 25 millisec
9be0: 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20  onds before the 
9bf0: 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20  first retry and 
9c00: 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69  with the delay i
9c10: 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20  ncreasing.** by 
9c20: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35  an additional 25
9c30: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69   milliseconds wi
9c40: 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65  th each subseque
9c50: 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a  nt retry.  This.
9c60: 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73  ** opcode allows
9c70: 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65   these two value
9c80: 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e  s (10 retries an
9c90: 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  d 25 millisecond
9ca0: 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74  s of delay).** t
9cb0: 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20  o be adjusted.  
9cc0: 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63  The values are c
9cd0: 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64  hanged for all d
9ce0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9cf0: 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68  ons.** within th
9d00: 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20  e same process. 
9d10: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
9d20: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9d30: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a   array of two.**
9d40: 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20   integers where 
9d50: 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65  the first intege
9d60: 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72  r i the new retr
9d70: 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20  y count and the 
9d80: 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65  second.** intege
9d90: 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20  r is the delay. 
9da0: 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67   If either integ
9db0: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
9dc0: 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67  then the setting
9dd0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
9de0: 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74  ed but instead t
9df0: 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
9e00: 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69  f that setting i
9e10: 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74  s written.** int
9e20: 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72  o the array entr
9e30: 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20  y, allowing the 
9e40: 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65  current retry se
9e50: 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20  ttings to be.** 
9e60: 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54  interrogated.  T
9e70: 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d  he zDbName param
9e80: 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e  eter is ignored.
9e90: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9ea0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
9eb0: 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20  T_WAL]].** ^The 
9ec0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
9ed0: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64  RSIST_WAL] opcod
9ee0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
9ef0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
9f00: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c   persistent [WAL
9f10: 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c   | Write Ahead L
9f20: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79  og] setting.  By
9f30: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75   default, the au
9f40: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65  xiliary.** write
9f50: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73   ahead log and s
9f60: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
9f70: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e  es used for tran
9f80: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a  saction control.
9f90: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ** are automatic
9fa0: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65  ally deleted whe
9fb0: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e  n the latest con
9fc0: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64  nection to the d
9fd0: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65  atabase.** close
9fe0: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73  s.  Setting pers
9ff0: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
a000: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c  causes those fil
a010: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66  es to persist af
a020: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50  ter.** close.  P
a030: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69  ersisting the fi
a040: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68  les is useful wh
a050: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  en other process
a060: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a  es that do not.*
a070: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72  * have write per
a080: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64  mission on the d
a090: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
a0a0: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
a0b0: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f   file want.** to
a0c0: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61   read the databa
a0d0: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20  se file, as the 
a0e0: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d  WAL and shared m
a0f0: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74  emory files must
a100: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64   exist.** in ord
a110: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
a120: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62  ase to be readab
a130: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  le.  The fourth 
a140: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
a150: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a160: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
a170: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
a180: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
a190: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
a1a0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
a1b0: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73   to disable pers
a1c0: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
a1d0: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70  or 1 to enable p
a1e0: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c  ersistent.** WAL
a1f0: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
a200: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
a210: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
a220: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a230: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72  rrent.** WAL per
a240: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67  sistence setting
a250: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a260: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
a270: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d  SAFE_OVERWRITE]]
a280: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a290: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
a2a0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a2b0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
a2c0: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
a2d0: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f  * persistent "po
a2e0: 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74  wersafe-overwrit
a2f0: 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74  e" or "PSOW" set
a300: 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20  ting.  The PSOW 
a310: 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72  setting.** deter
a320: 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54  mines the [SQLIT
a330: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
a340: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74  E_OVERWRITE] bit
a350: 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69   of the.** xDevi
a360: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
a370: 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66  s methods. The f
a380: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a390: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
a3a0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
a3b0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
a3c0: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
a3d0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
a3e0: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
a3f0: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
a400: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  e zero-damage mo
a410: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a420: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a  e zero-damage.**
a430: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
a440: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
a450: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
a460: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a470: 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61  rrent.** zero-da
a480: 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e  mage mode settin
a490: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
a4a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a4b0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
a4c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
a4d0: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
a4e0: 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  is invoked by SQ
a4f0: 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69  Lite after openi
a500: 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72  ng.** a write tr
a510: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64  ansaction to ind
a520: 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65  icate that, unle
a530: 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20  ss it is rolled 
a540: 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a  back for some.**
a550: 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74   reason, the ent
a560: 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ire database fil
a570: 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72  e will be overwr
a580: 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72  itten by the cur
a590: 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63  rent .** transac
a5a0: 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73  tion. This is us
a5b0: 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65  ed by VACUUM ope
a5c0: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c  rations..**.** <
a5d0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a5e0: 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  L_VFSNAME]].** ^
a5f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a600: 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64  L_VFSNAME] opcod
a610: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
a620: 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65   obtain the name
a630: 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53  s of.** all [VFS
a640: 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73  es] in the VFS s
a650: 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73  tack.  The names
a660: 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20   are of all VFS 
a670: 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a  shims and the.**
a680: 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65   final bottom-le
a690: 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74  vel VFS are writ
a6a0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
a6b0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
a6c0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
a6d0: 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73  c()] and the res
a6e0: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ult is stored in
a6f0: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
a700: 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ble.** that the 
a710: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
a720: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   of [sqlite3_fil
a730: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69  e_control()] poi
a740: 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63  nts to..** The c
a750: 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73  aller is respons
a760: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67  ible for freeing
a770: 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e   the memory when
a780: 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a   done.  As with.
a790: 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74  ** all file-cont
a7a0: 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  rol actions, the
a7b0: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74  re is no guarant
a7c0: 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c  ee that this wil
a7d0: 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f  l actually.** do
a7e0: 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c   anything.  Call
a7f0: 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69  ers should initi
a800: 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20  alize the char* 
a810: 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55  variable to a NU
a820: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  LL.** pointer in
a830: 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d   case this file-
a840: 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69  control is not i
a850: 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69  mplemented.  Thi
a860: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  s file-control.*
a870: 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  * is intended fo
a880: 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65  r diagnostic use
a890: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   only..**.** <li
a8a0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a8b0: 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  VFS_POINTER]].**
a8c0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a8d0: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d  NTL_VFS_POINTER]
a8e0: 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20   opcode finds a 
a8f0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74  pointer to the t
a900: 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53  op-level.** [VFS
a910: 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e  es] currently in
a920: 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67   use.  ^(The arg
a930: 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71  ument X in.** sq
a940: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a950: 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e  ol(db,SQLITE_FCN
a960: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58  TL_VFS_POINTER,X
a970: 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20  ) must be.** of 
a980: 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76  type "[sqlite3_v
a990: 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f  fs] **".  This o
a9a0: 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20  pcodes will set 
a9b0: 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74  *X.** to a point
a9c0: 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65  er to the top-le
a9d0: 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57  vel VFS.)^.** ^W
a9e0: 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75  hen there are mu
a9f0: 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73  ltiple VFS shims
aa00: 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74   in the stack, t
aa10: 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73  his opcode finds
aa20: 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f   the.** upper-mo
aa30: 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a  st shim only..**
aa40: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
aa50: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a  _FCNTL_PRAGMA]].
aa60: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b  ** ^Whenever a [
aa70: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
aa80: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20  t is parsed, an 
aa90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
aaa0: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63  AGMA] .** file c
aab0: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74  ontrol is sent t
aac0: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69  o the open [sqli
aad0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
aae0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
aaf0: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  * to the databas
ab00: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20  e file to which 
ab10: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65  the pragma state
ab20: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68  ment refers. ^Th
ab30: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
ab40: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
ab50: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
ab60: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72  control is an ar
ab70: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65  ray of.** pointe
ab80: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63  rs to strings (c
ab90: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20  har**) in which 
aba0: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65  the second eleme
abb0: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a  nt of the array.
abc0: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
abd0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64  f the pragma and
abe0: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65   the third eleme
abf0: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  nt is the argume
ac00: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61  nt to the.** pra
ac10: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  gma or NULL if t
ac20: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f  he pragma has no
ac30: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65   argument.  ^The
ac40: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a   handler for an.
ac50: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
ac60: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
ac70: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e  ntrol can option
ac80: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69  ally make the fi
ac90: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f  rst element.** o
aca0: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67  f the char** arg
acb0: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61  ument point to a
acc0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
acd0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
ace0: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20  printf()].** or 
acf0: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61  the equivalent a
ad00: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77  nd that string w
ad10: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72  ill become the r
ad20: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61  esult of the pra
ad30: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72  gma or.** the er
ad40: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74  ror message if t
ad50: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e  he pragma fails.
ad60: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
ad70: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
ad80: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
ad90: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
ada0: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e  OTFOUND], then n
adb0: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d  ormal .** [PRAGM
adc0: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f  A] processing co
add0: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68  ntinues.  ^If th
ade0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
adf0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
ae00: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
ae10: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
ae20: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73  n the parser ass
ae30: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
ae40: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64   VFS has handled
ae50: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65   the PRAGMA itse
ae60: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65  lf and the parse
ae70: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f  r generates a no
ae80: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  -op.** prepared 
ae90: 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73  statement if res
aea0: 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55  ult string is NU
aeb0: 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75  LL, or that retu
aec0: 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66  rns a copy.** of
aed0: 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69   the result stri
aee0: 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67  ng if the string
aef0: 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a   is non-NULL..**
af00: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
af10: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
af20: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
af30: 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c  rns.** any resul
af40: 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61  t code other tha
af50: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  n [SQLITE_OK] or
af60: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
af70: 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  D], that means.*
af80: 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65  * that the VFS e
af90: 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72  ncountered an er
afa0: 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69  ror while handli
afb0: 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20  ng the [PRAGMA] 
afc0: 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  and the.** compi
afd0: 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52  lation of the PR
afe0: 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20  AGMA fails with 
aff0: 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20  an error.  ^The 
b000: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b010: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
b020: 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20  ntrol occurs at 
b030: 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
b040: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e   pragma statemen
b050: 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73  t analysis and s
b060: 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20  o.** it is able 
b070: 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c  to override buil
b080: 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74  t-in [PRAGMA] st
b090: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
b0a0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b0b0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d  TL_BUSYHANDLER]]
b0c0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
b0d0: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
b0e0: 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  ER].** file-cont
b0f0: 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  rol may be invok
b100: 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20  ed by SQLite on 
b110: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
b120: 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72  e handle.** shor
b130: 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20  tly after it is 
b140: 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20  opened in order 
b150: 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73  to provide a cus
b160: 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63  tom VFS with acc
b170: 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  ess.** to the co
b180: 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68  nnections busy-h
b190: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  andler callback.
b1a0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b1b0: 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a   of type (void *
b1c0: 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79  *).** - an array
b1d0: 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29   of two (void *)
b1e0: 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72   values. The fir
b1f0: 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75  st (void *) actu
b200: 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74  ally points.** t
b210: 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
b220: 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f  type (int (*)(vo
b230: 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72  id *)). In order
b240: 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63   to invoke the c
b250: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75  onnections.** bu
b260: 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73  sy-handler, this
b270: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
b280: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
b290: 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69   the second (voi
b2a0: 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61  d *) in.** the a
b2b0: 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79  rray as the only
b2c0: 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74   argument. If it
b2d0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
b2e0: 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72  o, then the oper
b2f0: 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
b300: 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69  be retried. If i
b310: 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  t returns zero, 
b320: 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73  the custom VFS s
b330: 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68  hould abandon th
b340: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65  e.** current ope
b350: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ration..**.** <l
b360: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b370: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a  _TEMPFILENAME]].
b380: 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20  ** ^Application 
b390: 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b  can invoke the [
b3a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
b3b0: 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d  PFILENAME] file-
b3c0: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61  control.** to ha
b3d0: 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61  ve SQLite genera
b3e0: 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  te a.** temporar
b3f0: 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67  y filename using
b400: 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
b410: 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c  thm that is foll
b420: 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65  owed to generate
b430: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
b440: 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50  lenames for TEMP
b450: 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65   tables and othe
b460: 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e  r internal uses.
b470: 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e    The.** argumen
b480: 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68  t should be a ch
b490: 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  ar** which will 
b4a0: 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  be filled with t
b4b0: 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77  he filename.** w
b4c0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
b4d0: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
b4e0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
b4f0: 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72  ()].  The caller
b500: 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b   should.** invok
b510: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
b520: 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74  )] on the result
b530: 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f   to avoid a memo
b540: 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c  ry leak..**.** <
b550: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b560: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  L_MMAP_SIZE]].**
b570: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b580: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
b590: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
b5a0: 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73  ed to query or s
b5b0: 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75  et the.** maximu
b5c0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
b5d0: 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75  s that will be u
b5e0: 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d  sed for memory-m
b5f0: 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68  apped I/O..** Th
b600: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
b610: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
b620: 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74  ue of type sqlit
b630: 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a  e3_int64 that.**
b640: 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20   is an advisory 
b650: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
b660: 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  f bytes in the f
b670: 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61  ile to memory ma
b680: 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74  p.  The.** point
b690: 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  er is overwritte
b6a0: 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76  n with the old v
b6b0: 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74  alue.  The limit
b6c0: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
b6d0: 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  if.** the value 
b6e0: 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74  originally point
b6f0: 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76  ed to is negativ
b700: 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75  e, and so the cu
b710: 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20  rrent limit .** 
b720: 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62  can be queried b
b730: 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70  y passing in a p
b740: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61  ointer to a nega
b750: 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68  tive number.  Th
b760: 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  is.** file-contr
b770: 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  ol is used inter
b780: 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65  nally to impleme
b790: 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  nt [PRAGMA mmap_
b7a0: 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  size]..**.** <li
b7b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b7c0: 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  TRACE]].** The [
b7d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
b7e0: 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  CE] file control
b7f0: 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f   provides adviso
b800: 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ry information.*
b810: 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f  * to the VFS abo
b820: 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68  ut what the high
b830: 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65  er layers of the
b840: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72   SQLite stack ar
b850: 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73  e doing..** This
b860: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b870: 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46   used by some VF
b880: 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69  S activity traci
b890: 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54  ng [shims]..** T
b8a0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
b8b0: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
b8c0: 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72   string.  Higher
b8d0: 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a   layers in the.*
b8e0: 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d  * SQLite stack m
b8f0: 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74  ay generate inst
b900: 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69  ances of this fi
b910: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a  le control if.**
b920: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
b930: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f  _FCNTL_TRACE] co
b940: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
b950: 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
b960: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b970: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
b980: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b990: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
b9a0: 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  D] file control 
b9b0: 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61  interprets its a
b9c0: 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20  rgument as a.** 
b9d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
b9e0: 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69  teger and it wri
b9f0: 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e  tes a boolean in
ba00: 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20  to that integer 
ba10: 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20  depending.** on 
ba20: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
ba30: 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e  he file has been
ba40: 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c   renamed, moved,
ba50: 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63   or deleted sinc
ba60: 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73  e it.** was firs
ba70: 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  t opened..**.** 
ba80: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ba90: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
baa0: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  DLE]].** The [SQ
bab0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
bac0: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63  _SET_HANDLE] opc
bad0: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
bae0: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
baf0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
bb00: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
bb10: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61  ol method to swa
bb20: 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c  p the file handl
bb30: 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a  e with the one.*
bb40: 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
bb50: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
bb60: 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c  t.  This capabil
bb70: 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69  ity is used duri
bb80: 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e  ng testing.** an
bb90: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
bba0: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
bbb0: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73  n SQLITE_TEST is
bbc0: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
bbd0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
bbe0: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a  TL_WAL_BLOCK]].*
bbf0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
bc00: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69  NTL_WAL_BLOCK] i
bc10: 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68  s a signal to th
bc20: 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74  e VFS layer that
bc30: 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20   it might.** be 
bc40: 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20  advantageous to 
bc50: 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78  block on the nex
bc60: 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68  t WAL lock if th
bc70: 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d  e lock is not im
bc80: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61  mediately.** ava
bc90: 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c  ilable.  The WAL
bca0: 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65   subsystem issue
bcb0: 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75  s this signal du
bcc0: 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72  ring rare.** cir
bcd0: 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72  cumstances in or
bce0: 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f  der to fix a pro
bcf0: 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69  blem with priori
bd00: 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  ty inversion..**
bd10: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
bd20: 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d  ould <em>not</em
bd30: 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d  > use this file-
bd40: 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c  control..**.** <
bd50: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bd60: 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68  L_ZIPVFS]].** Th
bd70: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
bd80: 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69  ZIPVFS] opcode i
bd90: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79  s implemented by
bda0: 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c   zipvfs only. Al
bdb0: 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73  l other.** VFS s
bdc0: 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c  hould return SQL
bdd0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72  ITE_NOTFOUND for
bde0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a   this opcode..**
bdf0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
be00: 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20  _FCNTL_RBU]].** 
be10: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
be20: 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73  L_RBU] opcode is
be30: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
be40: 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
be50: 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52  used by.** the R
be60: 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c  BU extension onl
be70: 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46  y.  All other VF
be80: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  S should return 
be90: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
bea0: 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f  for.** this opco
beb0: 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  de.  .** </ul>.*
bec0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
bed0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
bee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
bef0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bf00: 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52  FCNTL_GET_LOCKPR
bf10: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a  OXYFILE       2.
bf20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bf30: 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_SET_LOCKPRO
bf40: 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23  XYFILE       3.#
bf50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bf60: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20  NTL_LAST_ERRNO  
bf70: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64              4.#d
bf80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bf90: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20  TL_SIZE_HINT    
bfa0: 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
bfb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bfc0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20  L_CHUNK_SIZE    
bfd0: 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
bfe0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bff0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
c000: 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
c010: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c020: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20  SYNC_OMITTED    
c030: 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e          8.#defin
c040: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
c050: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20  IN32_AV_RETRY   
c060: 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
c070: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45   SQLITE_FCNTL_PE
c080: 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20  RSIST_WAL       
c090: 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
c0a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
c0b0: 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  RWRITE          
c0c0: 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53      11.#define S
c0d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
c0e0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20  AME             
c0f0: 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51     12.#define SQ
c100: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
c110: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
c120: 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    13.#define SQL
c130: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
c140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c150: 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   14.#define SQLI
c160: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
c170: 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20  DLER            
c180: 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  15.#define SQLIT
c190: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
c1a0: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31  NAME           1
c1b0: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
c1c0: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
c1d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
c1e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c1f0: 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20  FCNTL_TRACE     
c200: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a               19.
c210: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c220: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20  CNTL_HAS_MOVED  
c230: 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23              20.#
c240: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c250: 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20  NTL_SYNC        
c260: 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64             21.#d
c270: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c280: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
c290: 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65  WO        22.#de
c2a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c2b0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
c2c0: 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 66  LE       23.#def
c2d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c2e0: 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20  _WAL_BLOCK      
c2f0: 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 69          24.#defi
c300: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c310: 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 20 20  ZIPVFS          
c320: 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e         25.#defin
c330: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52  e SQLITE_FCNTL_R
c340: 42 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20  BU              
c350: 20 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65        26.#define
c360: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
c370: 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  S_POINTER       
c380: 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20       27.#define 
c390: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55  SQLITE_FCNTL_JOU
c3a0: 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20  RNAL_POINTER    
c3b0: 20 20 20 20 32 38 0a 23 64 65 66 69 6e 65 20 53      28.#define S
c3c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42 20  QLITE_FCNTL_PDB 
c3d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c3e0: 20 20 20 32 39 0a 0a 2f 2a 20 64 65 70 72 65 63     29../* deprec
c3f0: 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64  ated names */.#d
c400: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54  efine SQLITE_GET
c410: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
c420: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
c430: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
c440: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  LE.#define SQLIT
c450: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
c460: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f  ILE      SQLITE_
c470: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52  FCNTL_SET_LOCKPR
c480: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20  OXYFILE.#define 
c490: 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e  SQLITE_LAST_ERRN
c4a0: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53 51  O             SQ
c4b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
c4c0: 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  ERRNO.../*.** CA
c4d0: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
c4e0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
c4f0: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
c500: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
c510: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
c520: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
c530: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
c540: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
c550: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
c560: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
c570: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
c580: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
c590: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
c5a0: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
c5b0: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
c5c0: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
c5d0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
c5e0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
c5f0: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
c600: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
c610: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
c620: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
c630: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
c640: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
c650: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
c660: 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e  adable Extension
c670: 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70   Thunk.**.** A p
c680: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6f 70  ointer to the op
c690: 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61 70 69  aque sqlite3_api
c6a0: 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75 63 74  _routines struct
c6b0: 75 72 65 20 69 73 20 70 61 73 73 65 64 20 61 73  ure is passed as
c6c0: 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70 61  .** the third pa
c6d0: 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74 72 79  rameter to entry
c6e0: 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64   points of [load
c6f0: 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d  able extensions]
c700: 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72 75 63  .  This.** struc
c710: 74 75 72 65 20 6d 75 73 74 20 62 65 20 74 79 70  ture must be typ
c720: 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65 72 20  edefed in order 
c730: 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63  to work around c
c740: 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73  ompiler warnings
c750: 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74  .** on some plat
c760: 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  forms..*/.typede
c770: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
c780: 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 71  _api_routines sq
c790: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
c7a0: 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  es;../*.** CAPI3
c7b0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
c7c0: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
c7d0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
c7e0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
c7f0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
c800: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
c810: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
c820: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
c830: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
c840: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
c850: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
c860: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
c870: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
c880: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
c890: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
c8a0: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
c8b0: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
c8c0: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
c8d0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
c8e0: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
c8f0: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
c900: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
c910: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
c920: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
c930: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
c940: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
c950: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
c960: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
c970: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
c980: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
c990: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
c9a0: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
c9b0: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
c9c0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
c9d0: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
c9e0: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
c9f0: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
ca00: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
ca10: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
ca20: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
ca30: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
ca40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
ca50: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
ca60: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
ca70: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
ca80: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
ca90: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
caa0: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
cab0: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
cac0: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
cad0: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
cae0: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
caf0: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
cb00: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
cb10: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
cb20: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
cb30: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
cb40: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
cb50: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
cb60: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
cb70: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
cb80: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
cb90: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
cba0: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
cbb0: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
cbc0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
cbd0: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
cbe0: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
cbf0: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
cc00: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
cc10: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
cc20: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
cc30: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
cc40: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
cc50: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
cc60: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
cc70: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
cc80: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
cc90: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
cca0: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
ccb0: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
ccc0: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
ccd0: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
cce0: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
ccf0: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
cd00: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
cd10: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
cd20: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
cd30: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
cd40: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
cd50: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
cd60: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
cd70: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
cd80: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
cd90: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
cda0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
cdb0: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
cdc0: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
cdd0: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
cde0: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
cdf0: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
ce00: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
ce10: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
ce20: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
ce30: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
ce40: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
ce50: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
ce60: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
ce70: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
ce80: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
ce90: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
cea0: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
ceb0: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
cec0: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
ced0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
cee0: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
cef0: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
cf00: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
cf10: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
cf20: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
cf30: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
cf40: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
cf50: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
cf60: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
cf70: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
cf80: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
cf90: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
cfa0: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
cfb0: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
cfc0: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
cfd0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
cfe0: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
cff0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
d000: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
d010: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
d020: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
d030: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
d040: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
d050: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
d060: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
d070: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
d080: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
d090: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
d0a0: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
d0b0: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
d0c0: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
d0d0: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
d0e0: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
d0f0: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
d100: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
d110: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
d120: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
d130: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
d140: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
d150: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
d160: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
d170: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
d180: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
d190: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
d1a0: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
d1b0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
d1c0: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
d1d0: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
d1e0: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
d1f0: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
d200: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
d210: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
d220: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
d230: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
d240: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
d250: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
d260: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
d270: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
d280: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
d290: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
d2a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
d2b0: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
d2c0: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
d2d0: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
d2e0: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
d2f0: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
d300: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
d310: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
d320: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
d330: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
d340: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
d350: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
d360: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d370: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
d380: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d390: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
d3a0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
d3b0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
d3c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d3d0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
d3e0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
d3f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
d400: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
d410: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d420: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
d430: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d440: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
d450: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d460: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
d470: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
d480: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
d490: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
d4a0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
d4b0: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
d4c0: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
d4d0: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
d4e0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
d4f0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
d500: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
d510: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
d520: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
d530: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
d540: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
d550: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
d560: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
d570: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
d580: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
d590: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
d5a0: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
d5b0: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
d5c0: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
d5d0: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
d5e0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
d5f0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
d600: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
d610: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
d620: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
d630: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
d640: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
d650: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
d660: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
d670: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
d680: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
d690: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
d6a0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
d6b0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
d6c0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
d6d0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
d6e0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
d6f0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d700: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
d710: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
d720: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
d730: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
d740: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
d750: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
d760: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
d770: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
d780: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
d790: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
d7a0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
d7b0: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
d7c0: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
d7d0: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
d7e0: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
d7f0: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
d800: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
d810: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
d820: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
d830: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
d840: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
d850: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
d860: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
d870: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
d880: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
d890: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
d8a0: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
d8b0: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
d8c0: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
d8d0: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
d8e0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
d8f0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
d900: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
d910: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
d920: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
d930: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
d940: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
d950: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
d960: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
d970: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
d980: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
d990: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
d9a0: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
d9b0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
d9c0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
d9d0: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
d9e0: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
d9f0: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
da00: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
da10: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
da20: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
da30: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
da40: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
da50: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
da60: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
da70: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
da80: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
da90: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
daa0: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
dab0: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
dac0: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
dad0: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
dae0: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
daf0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
db00: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
db10: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
db20: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
db30: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
db40: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
db50: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
db60: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
db70: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
db80: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
db90: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
dba0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
dbb0: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
dbc0: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
dbd0: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
dbe0: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
dbf0: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
dc00: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
dc10: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
dc20: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
dc30: 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
dc40: 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
dc50: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
dc60: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
dc70: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
dc80: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
dc90: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
dca0: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
dcb0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
dcc0: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
dcd0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
dce0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
dcf0: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
dd00: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
dd10: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
dd20: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
dd30: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
dd40: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
dd50: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
dd60: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
dd70: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
dd80: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
dd90: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
dda0: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
ddb0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
ddc0: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
ddd0: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
dde0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
ddf0: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
de00: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
de10: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
de20: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
de30: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
de40: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
de50: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
de60: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
de70: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
de80: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
de90: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
dea0: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
deb0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
dec0: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
ded0: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
dee0: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
def0: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
df00: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
df10: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
df20: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
df30: 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
df40: 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
df50: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
df60: 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
df70: 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
df80: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
df90: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
dfa0: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
dfb0: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
dfc0: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
dfd0: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
dfe0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
dff0: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
e000: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
e010: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
e020: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
e030: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
e040: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
e050: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
e060: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
e070: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
e080: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
e090: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
e0a0: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
e0b0: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
e0c0: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
e0d0: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
e0e0: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
e0f0: 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
e100: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
e110: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
e120: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
e130: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
e140: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
e150: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
e160: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
e170: 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
e180: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
e190: 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
e1a0: 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
e1b0: 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
e1c0: 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
e1d0: 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
e1e0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
e1f0: 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
e200: 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
e210: 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
e220: 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
e230: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
e240: 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
e250: 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
e260: 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
e270: 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
e280: 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
e290: 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
e2a0: 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
e2b0: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
e2c0: 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
e2d0: 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
e2e0: 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
e2f0: 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
e300: 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
e310: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
e320: 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
e330: 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
e340: 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
e350: 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
e360: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
e370: 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
e380: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
e390: 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
e3a0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
e3b0: 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
e3c0: 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
e3d0: 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
e3e0: 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
e3f0: 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
e400: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
e410: 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
e420: 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
e430: 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
e440: 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
e450: 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
e460: 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
e470: 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
e480: 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
e490: 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
e4a0: 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
e4b0: 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
e4c0: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
e4d0: 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
e4e0: 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
e4f0: 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
e500: 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
e510: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
e520: 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
e530: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
e540: 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
e550: 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
e560: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
e570: 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
e580: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
e590: 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
e5a0: 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
e5b0: 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
e5c0: 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
e5d0: 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
e5e0: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
e5f0: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
e600: 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
e610: 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
e620: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
e630: 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
e640: 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
e650: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
e660: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
e670: 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
e680: 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
e690: 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
e6a0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
e6b0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
e6c0: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
e6d0: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
e6e0: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
e6f0: 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
e700: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
e710: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
e720: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
e730: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
e740: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
e750: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
e760: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
e770: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
e780: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
e790: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
e7a0: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
e7b0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e7c0: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
e7d0: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
e7e0: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
e7f0: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
e800: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
e810: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
e820: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
e830: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
e840: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
e850: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e860: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
e870: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
e880: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
e890: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
e8a0: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
e8b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e8c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e8d0: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
e8e0: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
e8f0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e900: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e910: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
e920: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
e930: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
e940: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
e950: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
e960: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
e970: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
e980: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
e990: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e9a0: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
e9b0: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
e9c0: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
e9d0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
e9e0: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
e9f0: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
ea00: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
ea10: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
ea20: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
ea30: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
ea40: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
ea50: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
ea60: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
ea70: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
ea80: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
ea90: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
eaa0: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
eab0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
eac0: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
ead0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
eae0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
eaf0: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
eb00: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
eb10: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
eb20: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
eb30: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
eb40: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
eb50: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
eb60: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
eb70: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
eb80: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
eb90: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
eba0: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
ebb0: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
ebc0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
ebd0: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
ebe0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
ebf0: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
ec00: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
ec10: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
ec20: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
ec30: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
ec40: 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
ec50: 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
ec60: 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
ec70: 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
ec80: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
ec90: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
eca0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
ecb0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
ecc0: 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
ecd0: 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
ece0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
ecf0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
ed00: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
ed10: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
ed20: 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
ed30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
ed40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
ed50: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
ed60: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
ed70: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
ed80: 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
ed90: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
eda0: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
edb0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
edc0: 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  nded in future v
edd0: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
ede0: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
edf0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
ee00: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
ee10: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
ee20: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
ee30: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
ee40: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
ee50: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
ee60: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
ee70: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
ee80: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
ee90: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
eea0: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
eeb0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
eec0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
eed0: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
eee0: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
eef0: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
ef00: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
ef10: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
ef20: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
ef30: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
ef40: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
ef50: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
ef60: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
ef70: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
ef80: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
ef90: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
efa0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
efb0: 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
efc0: 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
efd0: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
efe0: 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
eff0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
f000: 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
f010: 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
f020: 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
f030: 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
f040: 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
f050: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
f060: 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
f070: 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
f080: 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
f090: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
f0a0: 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
f0b0: 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
f0c0: 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
f0d0: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
f0e0: 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
f0f0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
f100: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
f110: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
f120: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
f130: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
f140: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
f150: 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
f160: 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
f170: 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
f180: 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
f190: 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
f1a0: 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
f1b0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
f1c0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
f1d0: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
f1e0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
f1f0: 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
f200: 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
f210: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
f220: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
f230: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
f240: 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
f250: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
f260: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
f270: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
f280: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
f290: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
f2a0: 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
f2b0: 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
f2c0: 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
f2d0: 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
f2e0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
f2f0: 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
f300: 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
f310: 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
f320: 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
f330: 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
f340: 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
f350: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
f360: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
f370: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
f380: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
f390: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
f3a0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
f3b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
f3c0: 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
f3d0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
f3e0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
f3f0: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
f400: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
f410: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
f420: 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
f430: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
f440: 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
f450: 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
f460: 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
f470: 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
f480: 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20  as given on the 
f490: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
f4a0: 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
f4b0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
f4c0: 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
f4d0: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
f4e0: 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
f4f0: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
f500: 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
f510: 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
f520: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
f530: 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
f540: 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
f550: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
f560: 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
f570: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
f580: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
f590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f5a0: 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
f5b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f5c0: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
f5d0: 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
f5e0: 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
f5f0: 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
f600: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
f610: 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
f620: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
f630: 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
f640: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
f650: 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
f660: 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
f670: 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
f680: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
f690: 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
f6a0: 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
f6b0: 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
f6c0: 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
f6d0: 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
f6e0: 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
f6f0: 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
f700: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
f710: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
f720: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
f730: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
f740: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
f750: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
f760: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
f770: 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
f780: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
f790: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
f7a0: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
f7b0: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
f7c0: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
f7d0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
f7e0: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
f7f0: 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
f800: 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
f810: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
f820: 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
f830: 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
f840: 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
f850: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
f860: 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
f870: 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
f880: 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
f890: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
f8a0: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
f8b0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
f8c0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
f8d0: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
f8e0: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
f8f0: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
f900: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f910: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
f920: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
f930: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
f940: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
f950: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
f960: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f970: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
f980: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
f990: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f9a0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
f9b0: 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
f9c0: 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
f9d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f9e0: 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
f9f0: 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
fa00: 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
fa10: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
fa20: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
fa30: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
fa40: 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
fa50: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
fa60: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
fa70: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
fa80: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
fa90: 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
faa0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fab0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
fac0: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
fad0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
fae0: 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
faf0: 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
fb00: 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
fb10: 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
fb20: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fb30: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
fb40: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
fb50: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
fb60: 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
fb70: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
fb80: 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
fb90: 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
fba0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
fbb0: 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
fbc0: 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
fbd0: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
fbe0: 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
fbf0: 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
fc00: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
fc10: 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
fc20: 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
fc30: 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
fc40: 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
fc50: 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
fc60: 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
fc70: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
fc80: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
fc90: 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
fca0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fcb0: 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
fcc0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fcd0: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
fce0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fcf0: 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
fd00: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
fd10: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
fd20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fd30: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
fd40: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
fd50: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
fd60: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
fd70: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
fd80: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
fd90: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
fda0: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
fdb0: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
fdc0: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
fdd0: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
fde0: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
fdf0: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
fe00: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
fe10: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
fe20: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
fe30: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
fe40: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
fe50: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
fe60: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
fe70: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
fe80: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
fe90: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
fea0: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
feb0: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
fec0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
fed0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
fee0: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
fef0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
ff00: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
ff10: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ff20: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
ff30: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
ff40: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
ff50: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
ff60: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
ff70: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
ff80: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
ff90: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
ffa0: 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
ffb0: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
ffc0: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
ffd0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
ffe0: 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
fff0: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
10000 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
10010 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
10020 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
10030 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
10040 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
10050 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
10060 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10070 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
10080 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
10090 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
100a0 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
100b0 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
100c0 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
100d0 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
100e0 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
100f0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
10100 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
10110 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
10120 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
10130 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
10140 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
10150 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
10160 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
10170 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
10180 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
10190 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
101a0 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
101b0 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
101c0 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
101d0 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
101e0 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
101f0 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
10200 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
10210 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
10220 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
10230 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
10240 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
10250 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
10260 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
10270 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
10280 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
10290 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
102a0 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
102b0 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
102c0 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
102d0 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
102e0 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
102f0 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
10300 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
10310 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
10320 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
10330 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
10340 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
10350 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
10360 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
10370 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
10380 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
10390 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
103a0 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
103b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
103c0 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
103d0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
103e0 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
103f0 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
10400 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
10410 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
10420 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
10430 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
10440 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
10450 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
10460 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
10470 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10480 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
10490 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
104a0 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
104b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
104c0 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
104d0 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
104e0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
104f0 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
10500 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
10510 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
10520 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
10530 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
10540 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
10550 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
10560 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
10570 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
10580 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
10590 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
105a0 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
105b0 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
105c0 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
105d0 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
105e0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
105f0 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
10600 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
10610 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
10620 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
10630 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
10640 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
10650 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10660 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
10670 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
10680 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
10690 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
106a0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
106b0 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
106c0 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
106d0 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
106e0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
106f0 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
10700 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
10710 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
10720 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  .int sqlite3_ini
10730 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69  tialize(void);.i
10740 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nt sqlite3_shutd
10750 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  own(void);.int s
10760 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
10770 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
10780 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
10790 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
107a0 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
107b0 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
107c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
107d0 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
107e0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
107f0 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
10800 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
10810 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
10820 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
10830 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
10840 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
10850 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
10860 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
10870 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
10880 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
10890 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
108a0 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
108b0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
108c0 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
108d0 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
108e0 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
108f0 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
10900 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
10910 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c  l needs..**.** <
10920 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  b>The sqlite3_co
10930 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
10940 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
10950 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74  fe. The applicat
10960 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75  ion.** must ensu
10970 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
10980 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
10990 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
109a0 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
109b0 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
109c0 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
109d0 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20  ning.</b>.**.** 
109e0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
109f0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  ig() interface.*
10a00 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
10a10 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
10a20 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
10a30 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
10a40 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10a50 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
10a60 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
10a70 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
10a80 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
10a90 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
10aa0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
10ab0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
10ac0 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
10ad0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10ae0 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
10af0 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
10b00 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
10b10 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
10b20 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
10b30 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
10b40 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
10b50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
10b60 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
10b70 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
10b80 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
10b90 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
10ba0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
10bb0 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
10bc0 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
10bd0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10be0 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
10bf0 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
10c00 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
10c10 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
10c20 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
10c30 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
10c40 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
10c50 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
10c60 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
10c70 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10c80 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
10c90 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10ca0 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
10cb0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
10cc0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
10cd0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
10ce0 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
10cf0 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
10d00 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
10d10 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
10d20 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
10d30 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
10d40 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69  rror code]..*/.i
10d50 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
10d60 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
10d70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
10d80 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
10d90 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
10da0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
10db0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
10dc0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e  3_db_config() in
10dd0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
10de0 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72  to make configur
10df0 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
10e00 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20   to a [database 
10e10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
10e20 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73  e interface is s
10e30 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71  imilar to.** [sq
10e40 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
10e50 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20  except that the 
10e60 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f  changes apply to
10e70 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61   a single.** [da
10e80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10e90 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e  n] (specified in
10ea0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
10eb0 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent)..**.** The 
10ec0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
10ed0 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
10ee0 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69  nfig(D,V,...)  i
10ef0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
10f00 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
10f10 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  IDE | configurat
10f20 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69  ion verb] - an i
10f30 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20  nteger code .** 
10f40 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77  that indicates w
10f50 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68  hat aspect of th
10f60 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
10f70 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
10f80 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20   configured..** 
10f90 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
10fa0 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64  ents vary depend
10fb0 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69  ing on the confi
10fc0 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a  guration verb..*
10fd0 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73  *.** ^Calls to s
10fe0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10ff0 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  () return SQLITE
11000 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  _OK if and only 
11010 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69  if.** the call i
11020 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63  s considered suc
11030 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  cessful..*/.int 
11040 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
11050 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
11060 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
11070 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
11080 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
11090 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  tines.**.** An i
110a0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
110b0 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
110c0 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
110d0 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ween SQLite.** a
110e0 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  nd low-level mem
110f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
11100 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
11110 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73  his object is us
11120 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70  ed in only one p
11130 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69  lace in the SQLi
11140 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
11150 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
11160 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
11170 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20  s object is the 
11180 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b  argument to.** [
11190 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
111a0 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69  ] when the confi
111b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
111c0 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  is.** [SQLITE_CO
111d0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20  NFIG_MALLOC] or 
111e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
111f0 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20  ETMALLOC].  .** 
11200 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69  By creating an i
11210 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
11220 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61  object.** and pa
11230 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
11240 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
11250 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
11260 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63  OC]).** during c
11270 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e  onfiguration, an
11280 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
11290 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
112a0 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
112b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
112c0 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74  system for SQLit
112d0 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c  e to use for all
112e0 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d   of its.** dynam
112f0 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e  ic memory needs.
11300 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
11310 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69   SQLite comes wi
11320 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c  th several [buil
11330 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
11340 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20  cators].** that 
11350 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64  are perfectly ad
11360 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f  equate for the o
11370 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f  verwhelming majo
11380 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
11390 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74  ions.** and that
113a0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
113b0 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61  only useful to a
113c0 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f   tiny minority o
113d0 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
113e0 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a  * with specializ
113f0 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
11400 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74  tion requirement
11410 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  s.  This object 
11420 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20  is.** also used 
11430 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f  during testing o
11440 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  f SQLite in orde
11450 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20  r to specify an 
11460 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
11470 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
11480 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d  that simulates m
11490 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d  emory out-of-mem
114a0 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69  ory conditions i
114b0 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65  n.** order to ve
114c0 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
114d0 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66   recovers gracef
114e0 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a  ully from such.*
114f0 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a  * conditions..**
11500 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c  .** The xMalloc,
11510 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78   xRealloc, and x
11520 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73  Free methods mus
11530 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a  t work like the.
11540 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  ** malloc(), rea
11550 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
11560 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d  ) functions from
11570 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
11580 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c  library..** ^SQL
11590 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
115a0 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61  hat the second a
115b0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52  rgument to.** xR
115c0 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73  ealloc is always
115d0 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65   a value returne
115e0 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c  d by a prior cal
115f0 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a  l to xRoundup..*
11600 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
11610 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
11620 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
11630 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11640 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
11650 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
11660 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
11670 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
11680 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
11690 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
116a0 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
116b0 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
116c0 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
116d0 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
116e0 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
116f0 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
11700 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
11710 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
11720 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
11730 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
11740 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
11750 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
11760 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
11770 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
11780 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
11790 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
117a0 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
117b0 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
117c0 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
117d0 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
117e0 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
117f0 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61  * Every memory a
11800 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
11810 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f  t coming in thro
11820 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ugh [sqlite3_mal
11830 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  loc()].** or [sq
11840 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
11850 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f   first calls xRo
11860 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e  undup.  If xRoun
11870 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a  dup returns 0, .
11880 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74  ** that causes t
11890 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
118a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
118b0 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  on to fail..**.*
118c0 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
118d0 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
118e0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
118f0 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tor.  For exampl
11900 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
11910 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
11920 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
11930 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
11940 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
11950 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
11960 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
11970 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
11980 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
11990 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
119a0 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
119b0 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
119c0 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
119d0 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
119e0 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
119f0 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
11a00 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
11a10 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
11a20 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
11a30 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
11a40 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
11a50 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
11a60 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
11a70 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
11a80 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
11a90 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
11aa0 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
11ab0 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
11ac0 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
11ad0 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
11ae0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
11af0 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
11b00 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
11b10 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
11b20 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
11b30 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
11b40 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
11b50 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
11b60 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
11b70 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
11b80 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
11b90 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
11ba0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11bb0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
11bc0 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
11bd0 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
11be0 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
11bf0 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
11c00 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
11c10 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
11c20 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
11c30 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
11c40 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
11c50 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
11c60 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
11c70 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
11c80 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
11c90 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
11ca0 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
11cb0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
11cc0 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
11cd0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
11ce0 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
11cf0 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
11d00 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
11d10 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
11d20 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
11d30 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
11d40 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
11d50 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
11d60 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
11d70 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
11d80 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
11d90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
11da0 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
11db0 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
11dc0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
11dd0 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
11de0 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
11df0 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
11e00 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
11e10 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
11e20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
11e30 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
11e40 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
11e50 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
11e60 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
11e70 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
11e80 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
11e90 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
11ea0 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
11eb0 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
11ec0 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
11ed0 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
11ee0 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
11ef0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
11f00 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
11f10 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
11f20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
11f30 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
11f40 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
11f50 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
11f60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
11f70 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
11f80 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
11f90 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
11fa0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
11fb0 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
11fc0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
11fd0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11fe0 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion}.**.** These
11ff0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
12000 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
12010 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
12020 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
12030 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
12040 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
12050 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
12060 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12070 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
12080 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
12090 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
120a0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
120b0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
120c0 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
120d0 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
120e0 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
120f0 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
12100 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
12110 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
12120 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
12130 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
12140 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
12150 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
12160 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
12170 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12180 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
12190 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
121a0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
121b0 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
121c0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
121d0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
121e0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
121f0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
12200 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
12210 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
12220 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
12230 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
12240 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
12250 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
12260 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
12270 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
12280 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
12290 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
122a0 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68  de] to Single-th
122b0 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
122c0 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
122d0 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
122e0 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
122f0 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
12300 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
12310 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
12320 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
12330 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
12340 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
12350 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
12360 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
12370 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
12380 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
12390 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
123a0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
123b0 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72   change the [thr
123c0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f  eading mode] fro
123d0 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a  m its default.**
123e0 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65   value of Single
123f0 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b  -thread and so [
12400 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12410 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a  ] will return .*
12420 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
12430 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
12440 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
12450 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a  G_SINGLETHREAD.*
12460 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
12470 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
12480 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12490 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d  IG_MULTITHREAD]]
124a0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
124b0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
124c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
124d0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
124e0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
124f0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
12500 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
12510 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
12520 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
12530 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
12540 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
12550 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
12560 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12570 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
12580 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
12590 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
125a0 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
125b0 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
125c0 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
125d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
125e0 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
125f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
12600 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
12610 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
12620 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
12630 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
12640 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
12650 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
12660 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
12670 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
12680 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
12690 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
126a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
126b0 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
126c0 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
126d0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
126e0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
126f0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
12700 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
12710 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
12720 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
12730 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
12740 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
12750 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
12760 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
12770 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
12780 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
12790 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
127a0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
127b0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
127c0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
127d0 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
127e0 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
127f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12800 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d  FIG_SERIALIZED]]
12810 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12820 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
12830 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
12840 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
12850 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
12860 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
12870 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
12880 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
12890 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
128a0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
128b0 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
128c0 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
128d0 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
128e0 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
128f0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
12900 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
12910 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
12920 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
12930 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
12940 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
12950 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
12960 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12970 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
12980 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
12990 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
129a0 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
129b0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
129c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
129d0 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
129e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
129f0 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
12a00 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
12a10 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
12a20 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
12a30 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
12a40 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
12a50 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
12a60 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
12a70 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
12a80 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
12a90 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12aa0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
12ab0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
12ac0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12ad0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
12ae0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
12af0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
12b00 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
12b10 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
12b20 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
12b30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12b40 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
12b50 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
12b60 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
12b70 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
12b80 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
12b90 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12ba0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
12bb0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12bc0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
12bd0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12be0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
12bf0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
12c00 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  G_MALLOC option 
12c10 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
12c20 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
12c30 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
12c40 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
12c50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
12c60 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
12c70 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
12c80 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
12c90 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
12ca0 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
12cb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
12cc0 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
12cd0 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68  n place of.** th
12ce0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
12cf0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69  ion routines bui
12d00 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
12d10 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a  ^ ^SQLite makes.
12d20 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ** its own priva
12d30 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63  te copy of the c
12d40 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
12d50 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12d60 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ds] structure.**
12d70 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c   before the [sql
12d80 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63  ite3_config()] c
12d90 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64  all returns.</dd
12da0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12db0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
12dc0 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
12dd0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
12de0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
12df0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12e00 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f  _GETMALLOC optio
12e10 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
12e20 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
12e30 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
12e40 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
12e50 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12e60 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12e70 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73  cture..** The [s
12e80 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12e90 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
12ea0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
12eb0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
12ec0 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
12ed0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12ee0 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
12ef0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
12f00 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
12f10 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
12f20 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
12f30 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
12f40 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
12f50 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
12f60 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
12f70 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
12f80 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
12f90 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ample. </dd>.**.
12fa0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12fb0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c  IG_MEMSTATUS]] <
12fc0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12fd0 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
12fe0 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
12ff0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
13000 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65  ATUS option take
13010 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
13020 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a  t of type int,.*
13030 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  * interpreted as
13040 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63   a boolean, whic
13050 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
13060 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
13070 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72  tion of.** memor
13080 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
13090 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20  tistics. ^(When 
130a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
130b0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
130c0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68  .** disabled, th
130d0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  e following SQLi
130e0 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
130f0 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
13100 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
13110 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
13120 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
13130 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
13140 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
13150 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
13160 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
13170 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
13180 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
13190 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a  te3_status64()].
131a0 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
131b0 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
131c0 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
131d0 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
131e0 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
131f0 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
13200 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
13210 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
13220 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
13230 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
13240 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
13250 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
13260 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
13270 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13280 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
13290 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  H]] <dt>SQLITE_C
132a0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
132b0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
132c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
132d0 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 65  RATCH option spe
132e0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
132f0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a  memory buffer.**
13300 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
13310 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 63 68   use for scratch
13320 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72   memory.  ^(Ther
13330 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
13340 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49  ments.** to SQLI
13350 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
13360 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e  H:  A pointer an
13370 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
13380 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ed memory buffer
13390 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
133a0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
133b0 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64  ons will be.** d
133c0 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f  rawn, the size o
133d0 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61  f each scratch a
133e0 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a  llocation (sz),.
133f0 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ** and the maxim
13400 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72  um number of scr
13410 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
13420 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66   (N).)^.** The f
13430 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
13440 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
13450 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
13460 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
13470 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
13480 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
13490 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
134a0 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 68   not use more th
134b0 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62  an one scratch b
134c0 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61  uffers per threa
134d0 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  d..** ^SQLite wi
134e0 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73 74  ll never request
134f0 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
13500 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
13510 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74  han 6.** times t
13520 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
13530 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   size..** ^If SQ
13540 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73  Lite needs needs
13550 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73   additional.** s
13560 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65  cratch memory be
13570 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
13580 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f  vided by this co
13590 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
135a0 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71  on, then .** [sq
135b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
135c0 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20  will be used to 
135d0 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72  obtain the memor
135e0 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20  y needed.<p>.** 
135f0 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69 63  ^When the applic
13600 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61  ation provides a
13610 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72  ny amount of scr
13620 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e  atch memory usin
13630 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  g.** SQLITE_CONF
13640 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c 69  IG_SCRATCH, SQLi
13650 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 65  te avoids unnece
13660 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b  ssary large.** [
13670 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68  sqlite3_malloc|h
13680 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d  eap allocations]
13690 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 65  ..** This can he
136a0 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66  lp [Robson proof
136b0 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20  |prevent memory 
136c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
136d0 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61 70  res] due to heap
136e0 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  .** fragmentatio
136f0 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20  n in low-memory 
13700 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
13710 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
13720 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13730 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74  _PAGECACHE]] <dt
13740 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
13750 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
13760 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
13770 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
13780 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  HE option specif
13790 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f  ies a memory poo
137a0 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  l.** that SQLite
137b0 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65   can use for the
137c0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
137d0 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
137e0 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61  fault page.** ca
137f0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
13800 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
13810 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13820 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66  on is a no-op if
13830 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
13840 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
13850 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
13860 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
13870 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
13880 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e  CONFIG_PCACHE2].
13890 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
138a0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
138b0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
138c0 50 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69  PAGECACHE: A poi
138d0 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74  nter to.** 8-byt
138e0 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  e aligned memory
138f0 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a   (pMem), the siz
13900 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 63  e of each page c
13910 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a  ache line (sz),.
13920 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ** and the numbe
13930 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73  r of cache lines
13940 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
13950 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
13960 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
13970 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
13980 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
13990 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
139a0 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33  een 512 and 6553
139b0 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74  6) plus some ext
139c0 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 61 63  ra bytes for eac
139d0 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
139e0 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  .  ^The number o
139f0 66 20 65 78 74 72 61 20 62 79 74 65 73 20 6e 65  f extra bytes ne
13a00 65 64 65 64 20 62 79 20 74 68 65 20 70 61 67 65  eded by the page
13a10 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62   header.** can b
13a20 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
13a30 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ng [SQLITE_CONFI
13a40 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e  G_PCACHE_HDRSZ].
13a50 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  .** ^It is harml
13a60 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
13a70 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
13a80 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a  y,.** for the sz
13a90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
13aa0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63   larger than nec
13ab0 65 73 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65  essary.  The pMe
13ac0 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  m.** argument mu
13ad0 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
13ae0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  ULL pointer or a
13af0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
13b00 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
13b10 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
13b20 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
13b30 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69  N bytes, otherwi
13b40 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  se.** subsequent
13b50 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
13b60 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e  efined..** ^When
13b70 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c   pMem is not NUL
13b80 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73  L, SQLite will s
13b90 74 72 69 76 65 20 74 6f 20 75 73 65 20 74 68 65  trive to use the
13ba0 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
13bb0 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70  .** to satisfy p
13bc0 61 67 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c  age cache needs,
13bd0 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f   falling back to
13be0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13bf0 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65  ()] if.** a page
13c00 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c   cache line is l
13c10 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79  arger than sz by
13c20 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66  tes or if all of
13c30 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72   the pMem buffer
13c40 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74 65 64  .** is exhausted
13c50 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73  ..** ^If pMem is
13c60 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e   NULL and N is n
13c70 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61  on-zero, then ea
13c80 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
13c90 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61  ection.** does a
13ca0 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61  n initial bulk a
13cb0 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61  llocation for pa
13cc0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a  ge cache memory.
13cd0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
13ce0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69  _malloc()] suffi
13cf0 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68  cient for N cach
13d00 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20  e lines if N is 
13d10 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f  positive or.** o
13d20 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20  f -1024*N bytes 
13d30 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  if N is negative
13d40 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  , . ^If addition
13d50 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
13d60 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
13d70 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
13d80 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
13d90 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f   initial.** allo
13da0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c  cation, then SQL
13db0 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
13dc0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73  ite3_malloc()] s
13dd0 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61  eparately for ea
13de0 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  ch.** additional
13df0 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64   cache line. </d
13e00 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13e10 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
13e20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13e30 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
13e40 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
13e50 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
13e60 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
13e70 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
13e80 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c  fer .** that SQL
13e90 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72  ite will use for
13ea0 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
13eb0 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
13ec0 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62  ation needs.** b
13ed0 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
13ee0 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c  ided for by [SQL
13ef0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
13f00 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49  CH] and.** [SQLI
13f10 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13f20 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51  CHE]..** ^The SQ
13f30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
13f40 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
13f50 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c  available if SQL
13f60 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a  ite is compiled.
13f70 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 20 5b  ** with either [
13f80 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
13f90 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54  MSYS3] or [SQLIT
13fa0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
13fb0 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  ] and returns.**
13fc0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
13fd0 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72  if invoked other
13fe0 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  wise..** ^There 
13ff0 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
14000 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
14010 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e  NFIG_HEAP:.** An
14020 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
14030 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
14040 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
14050 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
14060 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
14070 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
14080 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
14090 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
140a0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
140b0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
140c0 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
140d0 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
140e0 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
140f0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
14100 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
14110 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
14120 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
14130 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
14140 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
14150 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
14160 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
14170 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
14180 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
14190 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
141a0 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
141b0 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
141c0 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
141d0 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
141e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
141f0 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
14200 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
14210 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
14220 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
14230 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
14240 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
14250 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
14260 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
14270 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
14280 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
14290 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
142a0 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
142b0 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
142c0 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
142d0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
142e0 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
142f0 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
14300 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14310 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
14320 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14330 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
14340 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14350 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f  E_CONFIG_MUTEX o
14360 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14370 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
14380 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ich is a.** poin
14390 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
143a0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
143b0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
143c0 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
143d0 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
143e0 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69  cifies alternati
143f0 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
14400 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
14410 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61  e used.** in pla
14420 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ce the mutex rou
14430 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
14440 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c   SQLite.)^  ^SQL
14450 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
14460 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
14470 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
14480 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
14490 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f  ] structure befo
144a0 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  re the call to.*
144b0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
144c0 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49  g()] returns. ^I
144d0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
144e0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
144f0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
14500 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
14510 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
14520 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
14530 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
14540 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
14550 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
14560 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
14570 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
14580 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
14590 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
145a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
145b0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
145c0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
145d0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
145e0 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
145f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14600 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c  FIG_GETMUTEX]] <
14610 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14620 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  _GETMUTEX</dt>.*
14630 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14640 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14650 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  TEX option takes
14660 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14670 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
14680 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
14690 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
146a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
146b0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
146c0 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
146d0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
146e0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
146f0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
14700 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
14710 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
14720 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
14730 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
14740 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
14750 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
14760 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
14770 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
14780 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
14790 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
147a0 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
147b0 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
147c0 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
147d0 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
147e0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
147f0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
14800 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
14810 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14820 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
14830 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
14840 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
14850 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
14860 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
14870 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
14880 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
14890 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
148a0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
148b0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
148c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
148d0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
148e0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
148f0 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
14900 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14910 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e  LOOKASIDE]] <dt>
14920 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14930 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
14940 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14950 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14960 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  DE option takes 
14970 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
14980 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  at determine.** 
14990 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65  the default size
149a0 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65   of lookaside me
149b0 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61  mory on each [da
149c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
149d0 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  n]..** The first
149e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
149f0 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
14a00 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
14a10 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73  r slot and the s
14a20 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d  econd is the num
14a30 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20  ber of.** slots 
14a40 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63  allocated to eac
14a50 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
14a60 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49  ction.)^  ^(SQLI
14a70 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
14a80 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20  IDE.** sets the 
14a90 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
14aa0 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
14ab0 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
14ac0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
14ad0 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c  * option to [sql
14ae0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
14af0 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
14b00 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
14b10 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
14b20 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
14b30 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
14b40 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
14b50 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14b60 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
14b70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14b80 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
14b90 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14ba0 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
14bb0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14bc0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
14bd0 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  h is .** a point
14be0 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
14bf0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14c00 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73  2] object.  This
14c10 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
14c20 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61  s.** the interfa
14c30 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70  ce to a custom p
14c40 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
14c50 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e  entation.)^.** ^
14c60 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
14c70 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
14c80 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
14c90 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64  ds2] object.</dd
14ca0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14cb0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
14cc0 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
14cd0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14ce0 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
14cf0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
14d00 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70  IG_GETPCACHE2 op
14d10 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14d20 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
14d30 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
14d40 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
14d50 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14d60 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  2] object.  SQLi
14d70 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20  te copies of.** 
14d80 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 67 65  the current page
14d90 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
14da0 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
14db0 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a  object.)^ </dd>.
14dc0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14dd0 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e  ONFIG_LOG]] <dt>
14de0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14df0 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54  G</dt>.** <dd> T
14e00 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14e10 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75  _LOG option is u
14e20 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
14e30 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67   the SQLite.** g
14e40 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67  lobal [error log
14e50 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49  ]..** (^The SQLI
14e60 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
14e70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
14e80 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e  rguments: a poin
14e90 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63  ter to a.** func
14ea0 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c  tion with a call
14eb0 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f   signature of vo
14ec0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  id(*)(void*,int,
14ed0 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a  const char*), .*
14ee0 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20  * and a pointer 
14ef0 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65  to void. ^If the
14f00 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
14f10 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69  r is not NULL, i
14f20 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  t is.** invoked 
14f30 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  by [sqlite3_log(
14f40 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61  )] to process ea
14f50 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74  ch logging event
14f60 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75  .  ^If the.** fu
14f70 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
14f80 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c  s NULL, the [sql
14f90 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65  ite3_log()] inte
14fa0 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20  rface becomes a 
14fb0 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76  no-op..** ^The v
14fc0 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74  oid pointer that
14fd0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   is the second a
14fe0 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54  rgument to SQLIT
14ff0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a  E_CONFIG_LOG is.
15000 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  ** passed throug
15010 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70  h as the first p
15020 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
15030 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
15040 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
15050 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20  nction whenever 
15060 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73  that function is
15070 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20   invoked.  ^The 
15080 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
15090 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65   to.** the logge
150a0 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20  r function is a 
150b0 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73  copy of the firs
150c0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
150d0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
150e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  .** [sqlite3_log
150f0 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20  ()] call and is 
15100 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61  intended to be a
15110 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
15120 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  r an.** [extende
15130 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20  d result code]. 
15140 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
15150 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
15160 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a  the logger is.**
15170 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74   log message aft
15180 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69  er formatting vi
15190 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  a [sqlite3_snpri
151a0 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53  ntf()]..** The S
151b0 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e  QLite logging in
151c0 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
151d0 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f  eentrant; the lo
151e0 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gger function.**
151f0 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65   supplied by the
15200 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
15210 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79  t not invoke any
15220 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
15230 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69  e..** In a multi
15240 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63  -threaded applic
15250 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69  ation, the appli
15260 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
15270 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
15280 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  n must be thread
15290 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  safe. </dd>.**.*
152a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
152b0 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_URI]] <dt>SQLI
152c0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a  TE_CONFIG_URI.**
152d0 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54   <dd>^(The SQLIT
152e0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74  E_CONFIG_URI opt
152f0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
15300 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
15310 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e  ype int..** If n
15320 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52  on-zero, then UR
15330 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
15340 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20  obally enabled. 
15350 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
15360 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65   is zero,.** the
15370 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
15380 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
15390 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68  led.)^ ^If URI h
153a0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
153b0 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20  lly.** enabled, 
153c0 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61  all filenames pa
153d0 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
153e0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
153f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a  e3_open_v2()],.*
15400 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
15410 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
15420 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
15430 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
15440 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
15450 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
15460 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
15470 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
15480 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
15490 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
154a0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
154b0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
154c0 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69  opened. ^If it i
154d0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
154e0 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
154f0 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
15500 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
15510 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
15520 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
15530 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
15540 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15550 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42  n is opened. ^(B
15560 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68  y default, URI h
15570 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
15580 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  lly.** disabled.
15590 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
155a0 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65  ue may be change
155b0 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77  d by compiling w
155c0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
155d0 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62  TE_USE_URI] symb
155e0 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a  ol defined.)^.**
155f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15600 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
15610 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
15620 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
15630 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
15640 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15650 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
15660 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70  NG_INDEX_SCAN op
15670 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
15680 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61  gle integer.** a
15690 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
156a0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
156b0 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64  a boolean in ord
156c0 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  er to enable or 
156d0 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75  disable.** the u
156e0 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
156f0 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20  ndices for full 
15700 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74  table scans in t
15710 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  he query optimiz
15720 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  er..** ^The defa
15730 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64  ult setting is d
15740 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20  etermined.** by 
15750 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f  the [SQLITE_ALLO
15760 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  W_COVERING_INDEX
15770 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SCAN] compile-t
15780 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69  ime option, or i
15790 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61  s "on".** if tha
157a0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
157b0 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ption is omitted
157c0 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79  ..** The ability
157d0 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20   to disable the 
157e0 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
157f0 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
15800 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20   table scans.** 
15810 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20  is because some 
15820 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65  incorrectly code
15830 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61  d legacy applica
15840 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66  tions might malf
15850 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20  unction.** when 
15860 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
15870 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72   is enabled.  Pr
15880 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c  oviding the abil
15890 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c  ity to.** disabl
158a0 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  e the optimizati
158b0 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c  on allows the ol
158c0 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69  der, buggy appli
158d0 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77  cation code to w
158e0 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63  ork.** without c
158f0 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20  hange even with 
15900 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
15910 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
15920 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15930 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
15940 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
15950 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
15960 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15970 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
15980 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
15990 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
159a0 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
159b0 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
159c0 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
159d0 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
159e0 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
159f0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
15a00 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
15a10 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64   no-ops..** </dd
15a20 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15a30 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d  _CONFIG_SQLLOG]]
15a40 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
15a50 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20  ONFIG_SQLLOG.** 
15a60 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
15a70 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
15a80 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63  e if sqlite is c
15a90 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
15aa0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
15ab0 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70  LE_SQLLOG] pre-p
15ac0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64  rocessor macro d
15ad0 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73  efined. The firs
15ae0 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  t argument shoul
15af0 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65  d.** be a pointe
15b00 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  r to a function 
15b10 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28  of type void(*)(
15b20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63  void*,sqlite3*,c
15b30 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
15b40 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
15b50 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70  should be of typ
15b60 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63  e (void*). The c
15b70 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
15b80 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72  ed by the librar
15b90 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65  y.** in three se
15ba0 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61  parate circumsta
15bb0 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64  nces, identified
15bc0 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61   by the value pa
15bd0 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66  ssed as the.** f
15be0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e  ourth parameter.
15bf0 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
15c00 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74  arameter is 0, t
15c10 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
15c20 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70   connection.** p
15c30 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
15c40 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73  ond argument has
15c50 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65   just been opene
15c60 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67  d. The third arg
15c70 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20  ument.** points 
15c80 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74  to a buffer cont
15c90 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20  aining the name 
15ca0 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  of the main data
15cb0 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68  base file. If th
15cc0 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
15cd0 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e  meter is 1, then
15ce0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
15cf0 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72  nt that the thir
15d00 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70  d parameter.** p
15d10 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73  oints to has jus
15d20 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e  t been executed.
15d30 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72   Or, if the four
15d40 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
15d50 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63  2, then.** the c
15d60 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20  onnection being 
15d70 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
15d80 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
15d90 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20  s being closed. 
15da0 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  The.** third par
15db0 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64  ameter is passed
15dc0 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61   NULL In this ca
15dd0 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  se.  An example 
15de0 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a  of using this.**
15df0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15e00 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65  ption can be see
15e10 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73  n in the "test_s
15e20 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20  qllog.c" source 
15e30 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63  file in.** the c
15e40 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20  anonical SQLite 
15e50 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64  source tree.</dd
15e60 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15e70 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
15e80 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
15e90 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
15ea0 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54  ZE.** <dd>^SQLIT
15eb0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
15ec0 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d  ZE takes two 64-
15ed0 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c  bit integer (sql
15ee0 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75  ite3_int64) valu
15ef0 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74  es.** that are t
15f00 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20  he default mmap 
15f10 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20  size limit (the 
15f20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15f30 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d  for.** [PRAGMA m
15f40 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74  map_size]) and t
15f50 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
15f60 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  ed mmap size lim
15f70 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  it..** ^The defa
15f80 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20  ult setting can 
15f90 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  be overridden by
15fa0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
15fb0 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a  onnection using.
15fc0 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50  ** either the [P
15fd0 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
15fe0 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20   command, or by 
15ff0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
16000 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
16010 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
16020 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d  ol.  ^(The maxim
16030 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
16040 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  size.** will be 
16050 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
16060 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 79 20  ed if necessary 
16070 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73 20  so that it does 
16080 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a  not exceed the.*
16090 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  * compile-time m
160a0 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65  aximum mmap size
160b0 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b   set by the.** [
160c0 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f  SQLITE_MAX_MMAP_
160d0 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SIZE] compile-ti
160e0 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20  me option.)^.** 
160f0 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d  ^If either argum
16100 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69  ent to this opti
16110 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  on is negative, 
16120 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65  then that argume
16130 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64  nt is.** changed
16140 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d   to its compile-
16150 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  time default..**
16160 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16170 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
16180 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
16190 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
161a0 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  HEAPSIZE.** <dd>
161b0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
161c0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
161d0 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  E option is only
161e0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
161f0 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
16200 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20  led for Windows 
16210 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
16220 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70  _WIN32_MALLOC] p
16230 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
16240 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e  ro.** defined. ^
16250 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
16260 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b  N32_HEAPSIZE tak
16270 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69  es a 32-bit unsi
16280 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c  gned integer val
16290 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69  ue.** that speci
162a0 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  fies the maximum
162b0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65   size of the cre
162c0 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a  ated heap..**.**
162d0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
162e0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a  _PCACHE_HDRSZ]].
162f0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16300 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
16310 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
16320 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
16330 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20  HE_HDRSZ option 
16340 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
16350 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
16360 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
16370 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
16380 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61   writes into tha
16390 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75  t integer the nu
163a0 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a  mber of extra.**
163b0 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65 20   bytes per page 
163c0 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61 63  required for eac
163d0 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54  h page in [SQLIT
163e0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
163f0 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75  HE]..** The amou
16400 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61 63  nt of extra spac
16410 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20 63  e required can c
16420 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20  hange depending 
16430 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c  on the compiler,
16440 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66  .** target platf
16450 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20  orm, and SQLite 
16460 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  version..**.** [
16470 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
16480 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  MASZ]].** <dt>SQ
16490 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
164a0 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
164b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
164c0 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
164d0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
164e0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e  r which.** is an
164f0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
16500 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20 22  r and sets the "
16510 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  Minimum PMA Size
16520 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74  " for the multit
16530 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65  hreaded.** sorte
16540 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  r to that intege
16550 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  r.  The default 
16560 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  minimum PMA Size
16570 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a   is set by the.*
16580 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52  * [SQLITE_SORTER
16590 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d  _PMASZ] compile-
165a0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65  time option.  Ne
165b0 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c 61  w threads are la
165c0 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c  unched.** to hel
165d0 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72  p with sort oper
165e0 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74  ations when mult
165f0 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e  ithreaded sortin
16600 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20  g.** is enabled 
16610 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47  (using the [PRAG
16620 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d  MA threads] comm
16630 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f  and) and the amo
16640 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a  unt of content.*
16650 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65  * to be sorted e
16660 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65 20  xceeds the page 
16670 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d  size times the m
16680 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a  inimum of the.**
16690 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73   [PRAGMA cache_s
166a0 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64  ize] setting and
166b0 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a   this value..**.
166c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
166d0 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
166e0 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  L]].** <dt>SQLIT
166f0 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
16700 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e  L_SPILL.** <dd>^
16710 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16720 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
16730 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
16740 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
16750 20 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65   which.** become
16760 73 20 74 68 65 20 5b 73 74 61 74 65 6d 65 6e 74  s the [statement
16770 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d   journal] spill-
16780 74 6f 2d 64 69 73 6b 20 74 68 72 65 73 68 6f 6c  to-disk threshol
16790 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65  d.  .** [Stateme
167a0 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65  nt journals] are
167b0 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20   held in memory 
167c0 75 6e 74 69 6c 20 74 68 65 69 72 20 73 69 7a 65  until their size
167d0 20 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65   (in bytes).** e
167e0 78 63 65 65 64 73 20 74 68 69 73 20 74 68 72 65  xceeds this thre
167f0 73 68 6f 6c 64 2c 20 61 74 20 77 68 69 63 68 20  shold, at which 
16800 70 6f 69 6e 74 20 74 68 65 79 20 61 72 65 20 77  point they are w
16810 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a  ritten to disk..
16820 2a 2a 20 4f 72 20 69 66 20 74 68 65 20 74 68 72  ** Or if the thr
16830 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74  eshold is -1, st
16840 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73  atement journals
16850 20 61 72 65 20 61 6c 77 61 79 73 20 68 65 6c 64   are always held
16860 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c 79 20  .** exclusively 
16870 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69  in memory..** Si
16880 6e 63 65 20 6d 61 6e 79 20 73 74 61 74 65 6d 65  nce many stateme
16890 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65  nt journals neve
168a0 72 20 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20  r become large, 
168b0 73 65 74 74 69 6e 67 20 74 68 65 20 73 70 69 6c  setting the spil
168c0 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20 74  l.** threshold t
168d0 6f 20 61 20 76 61 6c 75 65 20 73 75 63 68 20 61  o a value such a
168e0 73 20 36 34 4b 69 42 20 63 61 6e 20 67 72 65 61  s 64KiB can grea
168f0 74 6c 79 20 72 65 64 75 63 65 20 74 68 65 20 61  tly reduce the a
16900 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20  mount of.** I/O 
16910 72 65 71 75 69 72 65 64 20 74 6f 20 73 75 70 70  required to supp
16920 6f 72 74 20 73 74 61 74 65 6d 65 6e 74 20 72 6f  ort statement ro
16930 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64  llback..** The d
16940 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
16950 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73   this setting is
16960 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74   controlled by t
16970 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54  he.** [SQLITE_ST
16980 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f  MTJRNL_SPILL] co
16990 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
169a0 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  n..** </dl>.*/.#
169b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
169c0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
169d0 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
169e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
169f0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
16a00 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
16a10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16a20 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
16a30 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
16a40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16a50 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
16a60 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
16a70 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
16a80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16a90 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
16aa0 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
16ab0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
16ac0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
16ad0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
16ae0 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
16af0 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
16b00 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
16b10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
16b20 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
16b30 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
16b40 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
16b50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16b60 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
16b70 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
16b80 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
16b90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16ba0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
16bb0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
16bc0 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
16bd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
16be0 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
16bf0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
16c00 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
16c10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16c20 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
16c30 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
16c40 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
16c50 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
16c60 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
16c70 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
16c80 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
16c90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16ca0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16cb0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
16cc0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
16cd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
16ce0 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
16cf0 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
16d00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
16d10 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
16d20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
16d30 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16d40 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
16d50 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
16d60 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
16d70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
16d80 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
16d90 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
16da0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16db0 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a  CHE2      18  /*
16dc0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
16dd0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
16de0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16df0 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20  IG_GETPCACHE2   
16e00 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  19  /* sqlite3_p
16e10 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
16e20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16e30 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
16e40 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20  G_INDEX_SCAN 20 
16e50 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
16e60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16e70 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31  _SQLLOG       21
16e80 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f    /* xSqllog, vo
16e90 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
16ea0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
16eb0 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a  P_SIZE    22  /*
16ec0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20   sqlite3_int64, 
16ed0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f  sqlite3_int64 */
16ee0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16ef0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
16f00 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f  PSIZE      23  /
16f10 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23  * int nByte */.#
16f20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16f30 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
16f40 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20  Z        24  /* 
16f50 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66  int *psz */.#def
16f60 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16f70 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20  G_PMASZ         
16f80 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73        25  /* uns
16f90 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20  igned int szPma 
16fa0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16fb0 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
16fc0 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20  L_SPILL      26 
16fd0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
16fe0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16ff0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
17000 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
17010 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
17020 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
17030 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
17040 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
17050 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17060 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
17070 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
17080 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
17090 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
170a0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
170b0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
170c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
170d0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
170e0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
170f0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
17100 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
17110 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
17120 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
17130 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
17140 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
17150 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
17160 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
17170 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
17180 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
17190 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
171a0 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
171b0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
171c0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
171d0 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
171e0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
171f0 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
17200 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
17210 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
17220 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
17230 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
17240 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
17250 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
17260 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
17270 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
17280 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
17290 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
172a0 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
172b0 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
172c0 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
172d0 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
172e0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
172f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17300 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
17310 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
17320 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
17330 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
17340 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
17350 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
17360 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
17370 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
17380 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
17390 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
173a0 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
173b0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
173c0 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
173d0 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
173e0 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
173f0 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
17400 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
17410 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
17420 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
17430 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
17440 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
17450 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
17460 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
17470 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
17480 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
17490 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
174a0 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
174b0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
174c0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
174d0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
174e0 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
174f0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
17500 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
17510 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
17520 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
17530 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
17540 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
17550 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
17560 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
17570 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
17580 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
17590 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
175a0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
175b0 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
175c0 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
175d0 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
175e0 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
175f0 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
17600 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
17610 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
17620 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
17630 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
17640 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
17650 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
17660 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
17670 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
17680 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
17690 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
176a0 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
176b0 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
176c0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
176d0 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
176e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
176f0 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
17700 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
17710 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
17720 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
17730 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
17740 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
17750 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
17760 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
17770 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
17780 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
17790 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
177a0 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
177b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
177c0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
177d0 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
177e0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
177f0 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
17800 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
17810 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
17820 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
17830 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
17840 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
17850 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
17860 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
17870 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
17880 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
17890 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
178a0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
178b0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
178c0 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
178d0 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
178e0 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
178f0 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
17900 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
17910 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
17920 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17930 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
17940 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
17950 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
17960 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
17970 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
17980 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
17990 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
179a0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
179b0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
179c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
179d0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
179e0 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
179f0 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
17a00 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
17a10 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
17a20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17a30 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
17a40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
17a50 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
17a60 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
17a70 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
17a80 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
17a90 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
17aa0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
17ab0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
17ac0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
17ad0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
17ae0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
17af0 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
17b00 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
17b10 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
17b20 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
17b30 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
17b40 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
17b50 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
17b60 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
17b70 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
17b80 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
17b90 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
17ba0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
17bb0 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
17bc0 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
17bd0 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
17be0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
17bf0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17c00 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
17c10 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
17c20 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
17c30 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
17c40 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
17c50 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
17c60 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
17c70 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54  CONFIG_ENABLE_FT
17c80 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74  S3_TOKENIZER</dt
17c90 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
17ca0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
17cb0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
17cc0 62 6c 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75  ble the two-argu
17cd0 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20  ment.** version 
17ce0 6f 66 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b  of the [fts3_tok
17cf0 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69  enizer()] functi
17d00 6f 6e 20 77 68 69 63 68 20 69 73 20 70 61 72 74  on which is part
17d10 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33   of the.** [FTS3
17d20 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72  ] full-text sear
17d30 63 68 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73  ch engine extens
17d40 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  ion..** There sh
17d50 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
17d60 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
17d70 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
17d80 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
17d90 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
17da0 20 74 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33   to disable fts3
17db0 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a  _tokenizer() or.
17dc0 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
17dd0 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e  nable fts3_token
17de0 69 7a 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69  izer() or negati
17df0 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
17e00 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61  setting.** uncha
17e10 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
17e20 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
17e30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17e40 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
17e50 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
17e60 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
17e70 63 61 74 65 20 77 68 65 74 68 65 72 20 66 74 73  cate whether fts
17e80 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64  3_tokenizer is d
17e90 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
17ea0 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
17eb0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
17ec0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17ed0 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
17ee0 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
17ef0 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77  ich case the new
17f00 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
17f10 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
17f20 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
17f30 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
17f40 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e  NABLE_LOAD_EXTEN
17f50 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SION</dt>.** <dd
17f60 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
17f70 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
17f80 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
17f90 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
17fa0 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e  tension()].** in
17fb0 74 65 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64  terface independ
17fc0 65 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f  ently of the [lo
17fd0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
17fe0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  SQL function..**
17ff0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e   The [sqlite3_en
18000 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
18010 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c  ion()] API enabl
18020 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62  es or disables b
18030 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49  oth the.** C-API
18040 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
18050 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20  xtension()] and 
18060 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
18070 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e   [load_extension
18080 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  ()]..** There sh
18090 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
180a0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
180b0 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69  ..** When the fi
180c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
180d0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
180e0 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74  s 1, then only t
180f0 68 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65  he C-API is.** e
18100 6e 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53  nabled and the S
18110 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61  QL function rema
18120 69 6e 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49  ins disabled.  I
18130 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  f the first argu
18140 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20  ment to.** this 
18150 69 6e 74 65 72 66 61 63 65 20 69 73 20 30 2c 20  interface is 0, 
18160 74 68 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d  then both the C-
18170 41 50 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20  API and the SQL 
18180 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73  function are dis
18190 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  abled..** If the
181a0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
181b0 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63  is -1, then no c
181c0 68 61 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20  hanges are made 
181d0 74 6f 20 73 74 61 74 65 20 6f 66 20 65 69 74 68  to state of eith
181e0 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20  er the.** C-API 
181f0 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  or the SQL funct
18200 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ion..** The seco
18210 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
18220 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
18230 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
18240 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
18250 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
18260 61 74 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c  ate whether [sql
18270 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
18280 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ion()] interface
18290 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20  .** is disabled 
182a0 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f  or enabled follo
182b0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
182c0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
182d0 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20  meter may.** be 
182e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
182f0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
18300 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73  e new setting is
18310 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
18320 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ck..** </dd>.**.
18330 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
18340 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
18350 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
18360 20 20 20 20 20 20 20 20 20 20 31 30 30 31 20 2f            1001 /
18370 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20  * void* int int 
18380 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18390 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
183a0 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 20  E_FKEY          
183b0 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74   1002 /* int int
183c0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
183d0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
183e0 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  BLE_TRIGGER     
183f0 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69     1003 /* int i
18400 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
18410 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
18420 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e  NABLE_FTS3_TOKEN
18430 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74  IZER 1004 /* int
18440 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
18450 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18460 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54  _ENABLE_LOAD_EXT
18470 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69  ENSION 1005 /* i
18480 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a  nt int* */.../*.
18490 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
184a0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
184b0 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
184c0 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  odes.** METHOD: 
184d0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
184e0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
184f0 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
18500 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
18510 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
18520 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
18530 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
18540 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
18550 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72   ^The extended r
18560 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
18570 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
18580 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
18590 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
185a0 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ity..*/.int sqli
185b0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
185c0 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
185d0 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
185e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
185f0 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
18600 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  id.** METHOD: sq
18610 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  lite3.**.** ^Eac
18620 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20  h entry in most 
18630 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65  SQLite tables (e
18640 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f  xcept for [WITHO
18650 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
18660 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75  ).** has a uniqu
18670 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
18680 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
18690 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
186a0 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
186b0 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
186c0 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
186d0 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
186e0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
186f0 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
18700 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
18710 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
18720 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
18730 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
18740 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
18750 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
18760 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
18770 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
18780 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
18790 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
187a0 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
187b0 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
187c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
187d0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
187e0 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63  owid(D) interfac
187f0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
18800 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a  owid] of the .**
18810 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
18820 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
18830 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61   into a rowid ta
18840 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20  ble or [virtual 
18850 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74  table].** on dat
18860 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18870 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20   D..** ^Inserts 
18880 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f  into [WITHOUT RO
18890 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20  WID] tables are 
188a0 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a  not recorded..**
188b0 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
188c0 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74  ul [INSERT]s int
188d0 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a  o rowid tables.*
188e0 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
188f0 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61  rred on the data
18900 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18910 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  D, .** then sqli
18920 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
18930 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73  rowid(D) returns
18940 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49   zero..**.** ^(I
18950 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
18960 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
18970 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20  igger or within 
18980 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
18990 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65  ].** method, the
189a0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
189b0 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b  ill return the [
189c0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
189d0 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73  serted.** row as
189e0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
189f0 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
18a00 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20  table method is 
18a10 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
18a20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
18a30 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
18a40 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74  e method ends, t
18a50 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
18a60 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
18a70 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
18a80 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
18a90 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
18aa0 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  or virtual.** ta
18ab0 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e  ble method began
18ac0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
18ad0 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
18ae0 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
18af0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
18b00 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
18b10 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
18b20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
18b30 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
18b40 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
18b50 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
18b60 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
18b70 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
18b80 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
18b90 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
18ba0 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
18bb0 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
18bc0 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
18bd0 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
18be0 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
18bf0 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
18c00 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
18c10 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
18c20 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
18c30 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
18c40 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
18c50 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
18c60 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
18c70 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
18c80 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
18c90 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
18ca0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
18cb0 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
18cc0 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
18cd0 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
18ce0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
18cf0 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
18d00 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
18d10 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
18d20 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
18d30 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
18d40 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
18d50 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
18d60 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
18d70 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
18d80 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
18d90 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
18da0 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
18db0 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
18dc0 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
18dd0 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
18de0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
18df0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
18e00 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
18e10 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
18e20 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
18e30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
18e40 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
18e50 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
18e60 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
18e70 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
18e80 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
18e90 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
18ea0 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
18eb0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
18ec0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
18ed0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
18ee0 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
18ef0 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
18f00 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
18f10 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
18f20 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
18f30 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
18f40 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
18f50 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
18f60 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
18f70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18f80 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
18f90 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
18fa0 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ified.** METHOD:
18fb0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
18fc0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
18fd0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
18fe0 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
18ff0 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a  d, inserted or.*
19000 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  * deleted by the
19010 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
19020 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
19030 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
19040 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f  E.** statement o
19050 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
19060 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66  onnection specif
19070 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20  ied by the only 
19080 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45  parameter..** ^E
19090 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
190a0 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
190b0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
190c0 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c  t modify the val
190d0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
190e0 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  y this function.
190f0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61  .**.** ^Only cha
19100 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74  nges made direct
19110 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54  ly by the INSERT
19120 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
19130 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  TE statement are
19140 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d  .** considered -
19150 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   auxiliary chang
19160 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52  es caused by [CR
19170 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
19180 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66  riggers], .** [f
19190 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
191a0 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d  ns] or [REPLACE]
191b0 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
191c0 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63  lution are not c
191d0 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43  ounted..** .** C
191e0 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
191f0 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
19200 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e  epted by .** [IN
19210 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
19220 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72   | INSTEAD OF tr
19230 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20  iggers] are not 
19240 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61  counted. ^The va
19250 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64  lue .** returned
19260 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
19270 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c  ges() immediatel
19280 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52  y after an INSER
19290 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a  T, UPDATE or .**
192a0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
192b0 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20  t run on a view 
192c0 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20  is always zero. 
192d0 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
192e0 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61  e to real .** ta
192f0 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  bles are counted
19300 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61  ..**.** Things a
19310 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61  re more complica
19320 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74  ted if the sqlit
19330 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  e3_changes() fun
19340 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63  ction is.** exec
19350 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69  uted while a tri
19360 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20  gger program is 
19370 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61  running. This ma
19380 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a  y happen if the.
19390 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20  ** program uses 
193a0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
193b0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72  QL function], or
193c0 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63   if some other c
193d0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
193e0 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69  ion invokes sqli
193f0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69  te3_changes() di
19400 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61  rectly. Essentia
19410 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e  lly:.** .** <ul>
19420 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66  .**   <li> ^(Bef
19430 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74  ore entering a t
19440 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74  rigger program t
19450 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19460 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73  d by.**        s
19470 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
19480 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76   function is sav
19490 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72  ed. After the tr
194a0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a  igger program .*
194b0 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e  *        has fin
194c0 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69  ished, the origi
194d0 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73  nal value is res
194e0 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20  tored.)^.** .** 
194f0 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20    <li> ^(Within 
19500 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
19510 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55  m each INSERT, U
19520 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45  PDATE and DELETE
19530 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74   .**        stat
19540 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76  ement sets the v
19550 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
19560 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
19570 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70  () .**        up
19580 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73  on completion as
19590 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72   normal. Of cour
195a0 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77  se, this value w
195b0 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  ill not include 
195c0 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63  .**        any c
195d0 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64  hanges performed
195e0 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73   by sub-triggers
195f0 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33  , as the sqlite3
19600 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
19610 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c        value will
19620 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65   be saved and re
19630 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63  stored after eac
19640 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61  h sub-trigger ha
19650 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c  s run.)^.** </ul
19660 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d  >.** .** ^This m
19670 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65  eans that if the
19680 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66   changes() SQL f
19690 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69  unction (or simi
196a0 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20  lar) is used.** 
196b0 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53  by the first INS
196c0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
196d0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
196e0 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
196f0 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73  , it .** returns
19700 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65   the value as se
19710 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69  t when the calli
19720 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67  ng statement beg
19730 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  an executing..**
19740 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20   ^If it is used 
19750 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72  by the second or
19760 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68   subsequent such
19770 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
19780 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20  n a trigger .** 
19790 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c  program, the val
197a0 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c  ue returned refl
197b0 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20  ects the number 
197c0 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
197d0 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76   by the .** prev
197e0 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44  ious INSERT, UPD
197f0 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
19800 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
19810 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
19820 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
19830 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
19840 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
19850 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
19860 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
19870 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
19880 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
19890 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
198a0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
198b0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
198c0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
198d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
198e0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
198f0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
19900 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
19910 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
19920 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
19930 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
19940 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
19950 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
19960 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
19970 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
19980 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
19990 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d  ws Modified.** M
199a0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
199b0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
199c0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
199d0 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
199e0 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d  rows inserted, m
199f0 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65  odified or.** de
19a00 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e  leted by all [IN
19a10 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20  SERT], [UPDATE] 
19a20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
19a30 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64  ements completed
19a40 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61  .** since the da
19a50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19a60 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e  n was opened, in
19a70 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78  cluding those ex
19a80 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72  ecuted as.** par
19a90 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f  t of trigger pro
19aa0 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e  grams. ^Executin
19ab0 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65  g any other type
19ac0 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
19ad0 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66  t.** does not af
19ae0 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72  fect the value r
19af0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
19b00 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
19b10 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e  ()..** .** ^Chan
19b20 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74  ges made as part
19b30 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   of [foreign key
19b40 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e   actions] are in
19b50 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a  cluded in the.**
19b60 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73   count, but thos
19b70 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  e made as part o
19b80 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  f REPLACE constr
19b90 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  aint resolution 
19ba0 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61  are.** not. ^Cha
19bb0 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
19bc0 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70  hat are intercep
19bd0 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f  ted by INSTEAD O
19be0 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61  F triggers .** a
19bf0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
19c00 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  ** .** See also 
19c10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
19c20 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
19c30 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
19c40 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
19c50 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
19c60 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
19c70 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
19c80 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
19c90 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
19ca0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
19cb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19cc0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
19cd0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
19ce0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
19cf0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
19d00 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
19d10 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
19d20 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
19d30 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
19d40 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
19d50 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
19d60 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
19d70 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
19d80 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48  ng Query.** METH
19d90 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
19da0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
19db0 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
19dc0 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
19dd0 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
19de0 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
19df0 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
19e00 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
19e10 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
19e20 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
19e30 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
19e40 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
19e50 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
19e60 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
19e70 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
19e80 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
19e90 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
19ea0 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
19eb0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
19ec0 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
19ed0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
19ee0 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
19ef0 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
19f00 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
19f10 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
19f20 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
19f30 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
19f40 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
19f50 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
19f60 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
19f70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19f80 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
19f90 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
19fa0 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
19fb0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
19fc0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
19fd0 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
19fe0 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
19ff0 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
1a000 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
1a010 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1a020 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
1a030 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
1a040 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
1a050 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
1a060 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
1a070 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
1a080 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
1a090 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
1a0a0 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
1a0b0 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
1a0c0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
1a0d0 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
1a0e0 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
1a0f0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1a100 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1a110 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
1a120 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
1a130 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
1a140 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
1a150 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
1a160 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
1a170 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
1a180 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
1a190 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
1a1a0 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
1a1b0 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
1a1c0 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
1a1d0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1a1e0 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
1a1f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a200 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
1a210 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
1a220 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1a230 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1a240 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
1a250 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
1a260 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
1a270 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
1a280 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
1a290 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
1a2a0 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
1a2b0 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
1a2c0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
1a2d0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1a2e0 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
1a2f0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1a300 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1a310 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
1a320 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
1a330 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
1a340 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
1a350 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
1a360 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
1a370 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
1a380 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1a390 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
1a3a0 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
1a3b0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1a3c0 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
1a3d0 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
1a3e0 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
1a3f0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1a400 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1a410 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1a420 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1a430 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1a440 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1a450 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
1a460 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
1a470 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
1a480 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
1a490 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
1a4a0 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
1a4b0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1a4c0 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
1a4d0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
1a4e0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
1a4f0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
1a500 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a  ent Is Complete.
1a510 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1a520 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
1a530 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
1a540 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
1a550 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
1a560 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
1a570 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
1a580 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
1a590 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
1a5a0 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
1a5b0 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
1a5c0 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
1a5d0 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
1a5e0 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
1a5f0 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72  rsing.  ^These r
1a600 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31  outines return 1
1a610 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
1a620 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
1a630 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
1a640 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
1a650 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73   ^A statement is
1a660 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
1a670 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
1a680 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
1a690 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
1a6a0 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20  is not a prefix 
1a6b0 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72  of a.** well-for
1a6c0 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47  med CREATE TRIGG
1a6d0 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ER statement.  ^
1a6e0 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
1a6f0 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
1a700 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
1a710 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
1a720 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
1a730 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
1a740 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
1a750 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
1a760 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
1a770 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
1a780 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
1a790 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
1a7a0 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
1a7b0 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
1a7c0 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73  inator.  ^Whites
1a7d0 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d  pace.** and comm
1a7e0 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77  ents that follow
1a7f0 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63   the final semic
1a800 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64  olon are ignored
1a810 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
1a820 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30  outines return 0
1a830 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
1a840 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e  t is incomplete.
1a850 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72    ^If a.** memor
1a860 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
1a870 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ls, then SQLITE_
1a880 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65  NOMEM is returne
1a890 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
1a8a0 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
1a8b0 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
1a8c0 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
1a8d0 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
1a8e0 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
1a8f0 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
1a900 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20  .** ^(If SQLite 
1a910 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69  has not been ini
1a920 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b  tialized using [
1a930 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
1a940 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20  ze()] prior .** 
1a950 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  to invoking sqli
1a960 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1a970 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   then sqlite3_in
1a980 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
1a990 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74  voked.** automat
1a9a0 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
1a9b0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20  3_complete16(). 
1a9c0 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c   If that initial
1a9d0 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a  ization fails,.*
1a9e0 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
1a9f0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
1aa00 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1aa10 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65  ) will be non-ze
1aa20 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ro.** regardless
1aa30 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
1aa40 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c  ot the input SQL
1aa50 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a   is complete.)^.
1aa60 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
1aa70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
1aa80 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lete()] must be 
1aa90 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1aaa0 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e  d.** UTF-8 strin
1aab0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  g..**.** The inp
1aac0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
1aad0 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
1aae0 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
1aaf0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
1ab00 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
1ab10 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
1ab20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
1ab30 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
1ab40 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   *sql);.int sqli
1ab50 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
1ab60 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
1ab70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ab80 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
1ab90 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
1aba0 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
1abb0 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  rs.** KEYWORDS: 
1abc0 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61  {busy-handler ca
1abd0 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61  llback} {busy ha
1abe0 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  ndler}.** METHOD
1abf0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1ac00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73  ^The sqlite3_bus
1ac10 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29  y_handler(D,X,P)
1ac20 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1ac30 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1ac40 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68  n X.** that migh
1ac50 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
1ac60 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
1ac70 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
1ac80 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61  mpt is made to a
1ac90 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73 65  ccess a database
1aca0 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65   table associate
1acb0 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62  d with.** [datab
1acc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1acd0 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74  D when another t
1ace0 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63  hread.** or proc
1acf0 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62 6c  ess has the tabl
1ad00 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65  e locked..** The
1ad10 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1ad20 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63  ndler() interfac
1ad30 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70  e is used to imp
1ad40 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74  lement.** [sqlit
1ad50 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1ad60 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62  )] and [PRAGMA b
1ad70 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a  usy_timeout]..**
1ad80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79  .** ^If the busy
1ad90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1ada0 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
1adb0 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75  BUSY].** is retu
1adc0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
1add0 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
1ade0 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49  ng the lock.  ^I
1adf0 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
1ae00 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  ack.** is not NU
1ae10 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c  LL, then the cal
1ae20 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69  lback might be i
1ae30 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
1ae40 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
1ae50 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
1ae60 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79  ment to the busy
1ae70 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
1ae80 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
1ae90 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
1aea0 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
1aeb0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1aec0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1aed0 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  .  ^The second a
1aee0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
1aef0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  e busy handler c
1af00 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
1af10 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74  umber of times t
1af20 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e  hat the busy han
1af30 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e  dler has.** been
1af40 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75   invoked previou
1af50 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65  sly for the same
1af60 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
1af70 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79   ^If the.** busy
1af80 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1af90 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64  s 0, then no add
1afa0 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73  itional attempts
1afb0 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20   are made to.** 
1afc0 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
1afd0 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ase and [SQLITE_
1afe0 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65  BUSY] is returne
1aff0 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c  d.** to the appl
1b000 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20  ication..** ^If 
1b010 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1b020 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
1b030 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
1b040 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
1b050 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
1b060 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79  abase and the cy
1b070 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
1b080 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
1b090 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
1b0a0 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
1b0b0 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c  ntee that it wil
1b0c0 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
1b0d0 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
1b0e0 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e  ck contention. ^
1b0f0 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
1b100 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
1b110 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
1b120 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
1b130 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
1b140 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
1b150 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
1b160 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
1b170 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
1b180 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  on instead of in
1b190 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62  voking the .** b
1b1a0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
1b1b0 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
1b1c0 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
1b1d0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
1b1e0 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
1b1f0 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
1b200 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
1b210 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
1b220 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
1b230 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1b240 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
1b250 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
1b260 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
1b270 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
1b280 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
1b290 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
1b2a0 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
1b2b0 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1b2c0 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
1b2d0 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
1b2e0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
1b2f0 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
1b300 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
1b310 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
1b320 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
1b330 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
1b340 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
1b350 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
1b360 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
1b370 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
1b380 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
1b390 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
1b3a0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1b3b0 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
1b3c0 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
1b3d0 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
1b3e0 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
1b3f0 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
1b400 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
1b410 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
1b420 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
1b430 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
1b440 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1b450 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  L..**.** ^(There
1b460 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
1b470 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
1b480 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
1b490 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
1b4a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
1b4b0 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
1b4c0 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
1b4d0 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
1b4e0 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
1b4f0 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
1b500 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
1b510 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
1b520 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20  * or evaluating 
1b530 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1b540 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61  eout=N] will cha
1b550 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  nge the.** busy 
1b560 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73  handler and thus
1b570 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69   clear any previ
1b580 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68  ously set busy h
1b590 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
1b5a0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
1b5b0 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
1b5c0 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
1b5d0 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
1b5e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b5f0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1b600 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1b610 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  r.  In other wor
1b620 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20  ds,.** the busy 
1b630 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72  handler is not r
1b640 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73  eentrant.  Any s
1b650 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72  uch actions.** r
1b660 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
1b670 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20  ed behavior..** 
1b680 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c  .** A busy handl
1b690 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
1b6a0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
1b6b0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20  onnection.** or 
1b6c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1b6d0 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
1b6e0 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1b6f0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
1b700 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1b710 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28  sqlite3*,int(*)(
1b720 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a  void*,int),void*
1b730 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b740 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54  EF: Set A Busy T
1b750 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44  imeout.** METHOD
1b760 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1b770 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
1b780 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
1b790 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
1b7a0 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20  y handler] that 
1b7b0 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20  sleeps.** for a 
1b7c0 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
1b7d0 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20   of time when a 
1b7e0 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
1b7f0 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a    ^The handler.*
1b800 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  * will sleep mul
1b810 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
1b820 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  l at least "ms" 
1b830 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1b840 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65  sleeping.** have
1b850 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e   accumulated.  ^
1b860 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22  After at least "
1b870 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
1b880 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a   of sleeping,.**
1b890 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
1b8a0 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75  urns 0 which cau
1b8b0 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
1b8c0 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a  p()] to return.*
1b8d0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
1b8e0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
1b8f0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
1b900 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
1b910 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
1b920 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
1b930 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
1b940 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  andlers..**.** ^
1b950 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
1b960 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
1b970 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
1b980 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
1b990 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b9a0 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20  n] at any given 
1b9b0 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74  moment.  If anot
1b9c0 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
1b9d0 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20  .** was defined 
1b9e0 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33   (using [sqlite3
1b9f0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
1ba00 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ) prior to calli
1ba10 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  ng.** this routi
1ba20 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62  ne, that other b
1ba30 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
1ba40 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  leared.)^.**.** 
1ba50 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47  See also:  [PRAG
1ba60 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d  MA busy_timeout]
1ba70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1ba80 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
1ba90 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
1baa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1bab0 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
1bac0 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
1bad0 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54  g Queries.** MET
1bae0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1baf0 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67  ** This is a leg
1bb00 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  acy interface th
1bb10 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20  at is preserved 
1bb20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
1bb30 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20  mpatibility..** 
1bb40 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  Use of this inte
1bb50 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63  rface is not rec
1bb60 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  ommended..**.** 
1bb70 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62  Definition: A <b
1bb80 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62  >result table</b
1bb90 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61  > is memory data
1bba0 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74   structure creat
1bbb0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71  ed by the.** [sq
1bbc0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1bbd0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41  )] interface.  A
1bbe0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65   result table re
1bbf0 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d  cords the.** com
1bc00 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75  plete query resu
1bc10 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20  lts from one or 
1bc20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a  more queries..**
1bc30 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f  .** The table co
1bc40 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61  nceptually has a
1bc50 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1bc60 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75  and columns.  Bu
1bc70 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65  t.** these numbe
1bc80 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20  rs are not part 
1bc90 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
1bca0 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65  ble itself.  The
1bcb0 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72  se.** numbers ar
1bcc0 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72  e obtained separ
1bcd0 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65  ately.  Let N be
1bce0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
1bcf0 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20  ows.** and M be 
1bd00 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
1bd10 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  lumns..**.** A r
1bd20 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61  esult table is a
1bd30 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
1bd40 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
1bd50 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
1bd60 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61  ings..** There a
1bd70 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65  re (N+1)*M eleme
1bd80 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79  nts in the array
1bd90 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70  .  The first M p
1bda0 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a  ointers point.**
1bdb0 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
1bdc0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
1bdd0 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61    contain the na
1bde0 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  mes of the colum
1bdf0 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  ns..** The remai
1be00 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c  ning entries all
1be10 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20   point to query 
1be20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76  results.  NULL v
1be30 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20  alues result.** 
1be40 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  in NULL pointers
1be50 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  .  All other val
1be60 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72  ues are in their
1be70 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
1be80 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
1be90 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
1bea0 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  as returned by [
1beb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1bec0 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
1bed0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
1bee0 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e  ht consist of on
1bef0 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79  e or more memory
1bf00 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   allocations..**
1bf10 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
1bf20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74  to pass a result
1bf30 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20   table directly 
1bf40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
1bf50 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ()]..** A result
1bf60 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
1bf70 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69   deallocated usi
1bf80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
1bf90 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
1bfa0 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65   ^(As an example
1bfb0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1bfc0 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
1bfd0 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
1bfe0 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
1bff0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1c000 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1c010 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
1c020 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
1c030 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
1c040 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
1c050 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
1c060 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
1c070 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
1c080 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
1c090 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
1c0a0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1c0b0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  te>.**.** There 
1c0c0 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
1c0d0 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
1c0e0 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
1c0f0 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
1c100 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
1c110 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
1c120 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1c130 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
1c140 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
1c150 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
1c160 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
1c170 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
1c180 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1c190 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
1c1a0 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
1c1b0 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
1c1c0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
1c1d0 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
1c1e0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1c1f0 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
1c200 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1c210 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
1c220 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1c230 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
1c240 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
1c250 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
1c260 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
1c270 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
1c280 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
1c290 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1c2a0 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
1c2b0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1c2c0 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
1c2d0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1c2e0 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65  ble() function e
1c2f0 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20  valuates one or 
1c300 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  more.** semicolo
1c310 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
1c320 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
1c330 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
1c340 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  d UTF-8.** strin
1c350 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72  g of its 2nd par
1c360 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
1c370 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ns a result tabl
1c380 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e  e to the.** poin
1c390 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73  ter given in its
1c3a0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   3rd parameter..
1c3b0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20  **.** After the 
1c3c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20  application has 
1c3d0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68  finished with th
1c3e0 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71  e result from sq
1c3f0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1c400 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61  ),.** it must pa
1c410 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  ss the result ta
1c420 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ble pointer to s
1c430 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1c440 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  e() in order to.
1c450 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
1c460 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
1c470 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73  alloced.  Becaus
1c480 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
1c490 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
1c4a0 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77  loc()] happens w
1c4b0 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65  ithin sqlite3_ge
1c4c0 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63  t_table(), the c
1c4d0 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  alling.** functi
1c4e0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
1c4f0 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  to call [sqlite3
1c500 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c  _free()] directl
1c510 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c  y.  Only.** [sql
1c520 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1c530 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
1c540 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1c550 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
1c560 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
1c570 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1c580 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
1c590 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20   implemented as 
1c5a0 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
1c5b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
1c5c0 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74  c()].  The sqlit
1c5d0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72  e3_get_table() r
1c5e0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
1c5f0 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  have access.** t
1c600 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64  o any internal d
1c610 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
1c620 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73  f SQLite.  It us
1c630 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  es only the publ
1c640 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ic.** interface 
1c650 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41  defined here.  A
1c660 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c  s a consequence,
1c670 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
1c680 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61  ur in the.** wra
1c690 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69  pper layer outsi
1c6a0 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e  de of the intern
1c6b0 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  al [sqlite3_exec
1c6c0 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74  ()] call are not
1c6d0 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e  .** reflected in
1c6e0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
1c6f0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
1c700 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b  rcode()] or.** [
1c710 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1c720 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
1c730 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
1c740 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1c750 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
1c760 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
1c770 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1c780 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
1c790 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
1c7a0 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c  char ***pazResul
1c7b0 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73  t,    /* Results
1c7c0 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f   of the query */
1c7d0 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20  .  int *pnRow,  
1c7e0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
1c7f0 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
1c800 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
1c810 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d  /.  int *pnColum
1c820 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d  n,        /* Num
1c830 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  ber of result co
1c840 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65  lumns written he
1c850 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70  re */.  char **p
1c860 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a  zErrmsg       /*
1c870 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
1c880 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f  en here */.);.vo
1c890 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
1c8a0 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
1c8b0 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
1c8c0 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
1c8d0 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
1c8e0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
1c8f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1c900 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
1c910 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
1c920 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
1c930 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
1c940 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1c950 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72  rary..** These r
1c960 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61  outines understa
1c970 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63  nd most of the c
1c980 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74  ommon K&R format
1c990 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a  ting options,.**
1c9a0 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74   plus some addit
1c9b0 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61  ional non-standa
1c9c0 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61  rd formats, deta
1c9d0 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e  iled below..** N
1c9e0 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66  ote that some of
1c9f0 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72   the more obscur
1ca00 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  e formatting opt
1ca10 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74  ions from recent
1ca20 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74  .** C-library st
1ca30 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74  andards are omit
1ca40 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d  ted from this im
1ca50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a  plementation..**
1ca60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1ca70 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
1ca80 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1ca90 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
1caa0 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
1cab0 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
1cac0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
1cad0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
1cae0 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
1caf0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1cb00 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
1cb10 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
1cb20 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
1cb30 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
1cb40 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1cb50 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
1cb60 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
1cb70 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
1cb80 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
1cb90 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
1cba0 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
1cbb0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
1cbc0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
1cbd0 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
1cbe0 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
1cbf0 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
1cc00 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
1cc10 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
1cc20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
1cc30 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
1cc40 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
1cc50 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1cc60 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
1cc70 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
1cc80 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
1cc90 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
1cca0 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
1ccb0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
1ccc0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
1ccd0 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
1cce0 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
1ccf0 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
1cd00 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
1cd10 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
1cd20 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
1cd30 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
1cd40 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
1cd50 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
1cd60 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
1cd70 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
1cd80 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
1cd90 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
1cda0 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
1cdb0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
1cdc0 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
1cdd0 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
1cde0 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
1cdf0 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
1ce00 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
1ce10 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
1ce20 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
1ce30 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
1ce40 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
1ce50 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
1ce60 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
1ce70 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
1ce80 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
1ce90 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
1cea0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
1ceb0 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
1cec0 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
1ced0 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
1cee0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1cef0 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
1cf00 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
1cf10 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
1cf20 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
1cf30 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
1cf40 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
1cf50 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
1cf60 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
1cf70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
1cf80 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1cf90 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
1cfa0 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
1cfb0 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
1cfc0 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
1cfd0 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
1cfe0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1cff0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
1d000 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
1d010 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
1d020 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1d030 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ()..**.** These 
1d040 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
1d050 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
1d060 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
1d070 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
1d080 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
1d090 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
1d0a0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1d0b0 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
1d0c0 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
1d0d0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
1d0e0 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
1d0f0 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
1d100 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22  re "%q", "%Q", "
1d110 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  %w" and "%z" opt
1d120 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
1d130 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
1d140 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
1d150 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
1d160 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
1d170 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
1d180 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
1d190 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
1d1a0 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
1d1b0 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
1d1c0 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
1d1d0 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
1d1e0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1d1f0 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
1d200 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
1d210 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
1d220 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
1d230 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
1d240 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
1d250 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
1d260 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
1d270 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
1d280 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
1d290 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
1d2a0 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
1d2b0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1d2c0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1d2d0 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
1d2e0 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
1d2f0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1d300 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
1d310 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
1d320 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
1d330 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
1d340 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1d350 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1d360 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1d370 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1d380 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1d390 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
1d3a0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1d3b0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1d3c0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1d3d0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1d3e0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1d3f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1d400 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
1d410 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
1d420 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
1d430 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
1d440 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
1d450 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
1d460 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
1d470 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1d480 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1d490 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1d4a0 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
1d4b0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1d4c0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1d4d0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1d4e0 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
1d4f0 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
1d500 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
1d510 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
1d520 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
1d530 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
1d540 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1d550 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1d560 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1d570 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
1d580 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
1d590 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1d5a0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
1d5b0 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
1d5c0 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
1d5d0 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
1d5e0 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
1d5f0 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
1d600 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
1d610 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
1d620 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
1d630 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
1d640 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
1d650 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
1d660 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
1d670 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
1d680 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
1d690 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1d6a0 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
1d6b0 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
1d6c0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
1d6d0 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
1d6e0 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
1d6f0 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
1d700 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
1d710 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
1d720 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
1d730 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
1d740 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
1d750 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
1d760 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1d770 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1d780 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1d790 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1d7a0 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
1d7b0 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1d7c0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1d7d0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1d7e0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1d7f0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1d800 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1d810 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
1d820 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
1d830 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
1d840 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
1d850 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
1d860 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
1d870 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
1d880 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1d890 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d   ^(The "%w" form
1d8a0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73  atting option is
1d8b0 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70   like "%q" excep
1d8c0 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74  t that it expect
1d8d0 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61  s to.** be conta
1d8e0 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62  ined within doub
1d8f0 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61  le-quotes instea
1d900 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74  d of single quot
1d910 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73  es, and it.** es
1d920 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65  capes the double
1d930 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72  -quote character
1d940 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1d950 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20  single-quote.** 
1d960 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68  character.)^  Th
1d970 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e  e "%w" formattin
1d980 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65  g option is inte
1d990 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20  nded for safely 
1d9a0 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62  inserting.** tab
1d9b0 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61  le and column na
1d9c0 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74  mes into a const
1d9d0 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65  ructed SQL state
1d9e0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ment..**.** ^(Th
1d9f0 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
1da00 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
1da10 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
1da20 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
1da30 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
1da40 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
1da50 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
1da60 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
1da70 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
1da80 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
1da90 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
1daa0 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a  ing.)^.*/.char *
1dab0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1dac0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
1dad0 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1dae0 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
1daf0 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1db00 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
1db10 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1db20 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
1db30 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
1db40 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  3_vsnprintf(int,
1db50 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1db60 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a  *, va_list);../*
1db70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1db80 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
1db90 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
1dba0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
1dbb0 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
1dbc0 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
1dbd0 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
1dbe0 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
1dbf0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
1dc00 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
1dc10 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
1dc20 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
1dc30 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
1dc40 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
1dc50 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
1dc60 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
1dc70 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
1dc80 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
1dc90 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
1dca0 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
1dcb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1dcc0 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
1dcd0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1dce0 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
1dcf0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
1dd00 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
1dd10 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
1dd20 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
1dd30 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
1dd40 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
1dd50 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
1dd60 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
1dd70 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
1dd80 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1dd90 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
1dda0 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
1ddb0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1ddc0 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
1ddd0 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
1dde0 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
1ddf0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
1de00 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
1de10 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1de20 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73  N) routine works
1de30 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71   just like.** sq
1de40 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
1de50 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73  except that N is
1de60 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d   an unsigned 64-
1de70 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74  bit integer inst
1de80 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e  ead.** of a sign
1de90 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65  ed 32-bit intege
1dea0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
1deb0 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
1dec0 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
1ded0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
1dee0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1def0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1df00 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1df10 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
1df20 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
1df30 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
1df40 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1df50 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
1df60 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
1df70 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
1df80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1df90 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
1dfa0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
1dfb0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1dfc0 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
1dfd0 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
1dfe0 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
1dff0 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
1e000 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
1e010 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
1e020 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
1e030 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
1e040 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
1e050 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
1e060 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1e070 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
1e080 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
1e090 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
1e0a0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1e0b0 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
1e0c0 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
1e0d0 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
1e0e0 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
1e0f0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
1e100 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
1e110 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
1e120 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1e130 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
1e140 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1e150 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74  realloc(X,N) int
1e160 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
1e170 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
1e180 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
1e190 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61  cation X to be a
1e1a0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e  t least N bytes.
1e1b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61  .** ^If the X pa
1e1c0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1e1d0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a  e3_realloc(X,N).
1e1e0 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
1e1f0 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
1e200 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
1e210 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
1e220 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1e230 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  (N)..** ^If the 
1e240 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  N parameter to s
1e250 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1e260 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  ,N) is zero or.*
1e270 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
1e280 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1e290 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
1e2a0 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
1e2b0 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a  qlite3_free(X)..
1e2c0 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c  ** ^sqlite3_real
1e2d0 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
1e2e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1e2f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1e300 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
1e310 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
1e320 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75   or NULL if insu
1e330 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
1e340 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
1e350 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
1e360 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
1e370 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
1e380 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
1e390 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
1e3a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
1e3b0 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
1e3c0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
1e3d0 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
1e3e0 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
1e3f0 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70  c(X,N) and the p
1e400 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1e410 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  is freed..** ^If
1e420 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1e430 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55  (X,N) returns NU
1e440 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69  LL and N is posi
1e450 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a  tive, then the.*
1e460 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  * prior allocati
1e470 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  on is not freed.
1e480 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1e490 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c  te3_realloc64(X,
1e4a0 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f  N) interfaces wo
1e4b0 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a  rks the same as.
1e4c0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ** sqlite3_reall
1e4d0 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74  oc(X,N) except t
1e4e0 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69  hat N is a 64-bi
1e4f0 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
1e500 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  er instead.** of
1e510 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64   a 32-bit signed
1e520 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
1e530 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72  ^If X is a memor
1e540 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65  y allocation pre
1e550 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
1e560 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
1e570 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  lloc(),.** sqlit
1e580 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73  e3_malloc64(), s
1e590 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1e5a0 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  , or sqlite3_rea
1e5b0 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a  lloc64(), then.*
1e5c0 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  * sqlite3_msize(
1e5d0 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  X) returns the s
1e5e0 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f  ize of that memo
1e5f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e  ry allocation in
1e600 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20   bytes..** ^The 
1e610 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1e620 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  y sqlite3_msize(
1e630 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67  X) might be larg
1e640 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62  er than the numb
1e650 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72  er.** of bytes r
1e660 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20  equested when X 
1e670 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20  was allocated.  
1e680 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20  ^If X is a NULL 
1e690 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20  pointer then.** 
1e6a0 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1e6b0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20   returns zero.  
1e6c0 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73  If X points to s
1e6d0 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73  omething that is
1e6e0 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69   not.** the begi
1e6f0 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20  nning of memory 
1e700 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69  allocation, or i
1e710 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  f it points to a
1e720 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c   formerly.** val
1e730 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  id memory alloca
1e740 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f  tion that has no
1e750 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68  w been freed, th
1e760 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
1e770 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73  ** of sqlite3_ms
1e780 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69  ize(X) is undefi
1e790 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79  ned and possibly
1e7a0 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
1e7b0 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75  ^The memory retu
1e7c0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1e7d0 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65  malloc(), sqlite
1e7e0 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20  3_realloc(),.** 
1e7f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1e800 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
1e810 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69  realloc64().** i
1e820 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
1e830 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
1e840 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
1e850 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
1e860 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
1e870 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
1e880 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
1e890 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
1e8a0 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
1e8b0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
1e8c0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
1e8d0 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
1e8e0 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
1e8f0 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
1e900 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
1e910 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
1e920 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
1e930 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
1e940 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
1e950 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
1e960 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
1e970 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
1e980 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
1e990 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
1e9a0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
1e9b0 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
1e9c0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  sed..**.** Prior
1e9d0 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
1e9e0 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57  on 3.7.10, the W
1e9f0 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
1ea00 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64  ace layer called
1ea10 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
1ea20 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1ea30 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
1ea40 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
1ea50 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
1ea60 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
1ea70 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
1ea80 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
1ea90 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
1eaa0 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
1eab0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57  the particular W
1eac0 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
1ead0 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
1eae0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
1eaf0 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c  s were detected,
1eb00 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72   but.** they wer
1eb10 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
1eb20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
1eb30 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
1eb40 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
1eb50 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
1eb60 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
1eb70 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
1eb80 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
1eb90 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
1eba0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1ebb0 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
1ebc0 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
1ebd0 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
1ebe0 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
1ebf0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
1ec00 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1ec10 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1ec20 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
1ec30 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
1ec40 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
1ec50 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1ec60 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
1ec70 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
1ec80 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
1ec90 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
1eca0 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
1ecb0 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
1ecc0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
1ecd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1ece0 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
1ecf0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
1ed00 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
1ed10 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74  3_malloc64(sqlit
1ed20 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64  e3_uint64);.void
1ed30 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
1ed40 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
1ed50 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1ed60 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71  lloc64(void*, sq
1ed70 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76  lite3_uint64);.v
1ed80 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1ed90 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33  (void*);.sqlite3
1eda0 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
1edb0 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  msize(void*);../
1edc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1edd0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
1ede0 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
1edf0 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
1ee00 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
1ee10 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
1ee20 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
1ee30 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
1ee40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
1ee50 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1ee60 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
1ee70 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
1ee80 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
1ee90 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
1eea0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1eeb0 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
1eec0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1eed0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
1eee0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1eef0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1ef00 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
1ef10 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
1ef20 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
1ef30 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
1ef40 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1ef50 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1ef60 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
1ef70 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
1ef80 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
1ef90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1efa0 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
1efb0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1efc0 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
1efd0 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
1efe0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1eff0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1f000 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1f010 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1f020 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
1f030 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
1f040 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
1f050 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
1f060 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1f070 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
1f080 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
1f090 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
1f0a0 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
1f0b0 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
1f0c0 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
1f0d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
1f0e0 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
1f0f0 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
1f100 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
1f110 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
1f120 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
1f130 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1f140 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
1f150 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
1f160 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
1f170 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1f180 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
1f190 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
1f1a0 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
1f1b0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1f1c0 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
1f1d0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1f1e0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
1f1f0 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65  reset..*/.sqlite
1f200 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1f210 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
1f220 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
1f230 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1f240 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
1f250 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
1f260 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
1f270 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
1f280 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
1f290 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
1f2a0 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
1f2b0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
1f2c0 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
1f2d0 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
1f2e0 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
1f2f0 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
1f300 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
1f310 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
1f320 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
1f330 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
1f340 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
1f350 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
1f360 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
1f370 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
1f380 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
1f390 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
1f3a0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
1f3b0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
1f3c0 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
1f3d0 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
1f3e0 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
1f3f0 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
1f400 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
1f410 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
1f420 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
1f430 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
1f440 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54   buffer P..** ^T
1f450 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63  he P parameter c
1f460 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  an be a NULL poi
1f470 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  nter..**.** ^If 
1f480 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73  this routine has
1f490 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f   not been previo
1f4a0 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69  usly called or i
1f4b0 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a  f the previous.*
1f4c0 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73  * call had N les
1f4d0 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20  s than one or a 
1f4e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
1f4f0 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e   P, then the PRN
1f500 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75  G is.** seeded u
1f510 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20  sing randomness 
1f520 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68  obtained from th
1f530 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
1f540 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64  thod of.** the d
1f550 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1f560 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  vfs] object..** 
1f570 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73  ^If the previous
1f580 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
1f590 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f  utine had an N o
1f5a0 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20  f 1 or more and 
1f5b0 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20  a.** non-NULL P 
1f5c0 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d  then the pseudo-
1f5d0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
1f5e0 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
1f5f0 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
1f600 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
1f610 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
1f620 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
1f630 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  ethod..*/.void s
1f640 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
1f650 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
1f660 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f670 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
1f680 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
1f690 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48  allbacks.** METH
1f6a0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1f6b0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1f6c0 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74  registers an aut
1f6d0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1f6e0 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
1f6f0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1f700 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
1f710 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
1f720 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
1f730 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
1f740 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1f750 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
1f760 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
1f770 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
1f780 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1f790 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1f7a0 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
1f7b0 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
1f7c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1f7d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1f7e0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1f7f0 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a  .  ^At various.*
1f800 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
1f810 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
1f820 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
1f830 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
1f840 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
1f850 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
1f860 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
1f870 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1f880 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
1f890 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
1f8a0 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54  are allowed.  ^T
1f8b0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1f8c0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
1f8d0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1f8e0 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
1f8f0 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
1f900 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
1f910 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
1f920 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
1f930 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
1f940 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
1f950 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
1f960 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
1f970 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
1f980 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
1f990 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
1f9a0 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
1f9b0 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20   an error.  ^If 
1f9c0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1f9d0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
1f9e0 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
1f9f0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1fa00 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
1fa10 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
1fa20 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
1fa30 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
1fa40 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
1fa50 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1fa60 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
1fa70 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
1fa80 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1fa90 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
1faa0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
1fab0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1fac0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
1fad0 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
1fae0 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
1faf0 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20  d is ok.  ^When 
1fb00 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1fb10 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
1fb20 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
1fb30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1fb40 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1fb50 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1fb60 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
1fb70 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1fb80 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1fb90 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
1fba0 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
1fbb0 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a  is denied. .**.*
1fbc0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
1fbd0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1fbe0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1fbf0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
1fc00 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
1fc10 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
1fc20 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1fc30 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
1fc40 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
1fc50 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
1fc60 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1fc70 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
1fc80 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
1fc90 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
1fca0 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
1fcb0 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
1fcc0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54  e authorized. ^T
1fcd0 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
1fce0 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
1fcf0 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
1fd00 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
1fd10 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
1fd20 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
1fd30 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61  ditional.** deta
1fd40 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
1fd50 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1fd60 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rized..**.** ^If
1fd70 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
1fd80 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
1fd90 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
1fda0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1fdb0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
1fdc0 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
1fdd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
1fde0 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
1fdf0 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
1fe00 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
1fe10 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
1fe20 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
1fe30 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
1fe40 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
1fe50 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
1fe60 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
1fe70 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
1fe80 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
1fe90 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1fea0 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
1feb0 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
1fec0 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
1fed0 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
1fee0 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  e..** ^If the ac
1fef0 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1ff00 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64  LITE_DELETE] and
1ff10 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1ff20 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
1ff30 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1ff40 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61  e [DELETE] opera
1ff50 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75  tion proceeds bu
1ff60 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61  t the.** [trunca
1ff70 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
1ff80 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64   is disabled and
1ff90 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65   all rows are de
1ffa0 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c  leted individual
1ffb0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ly..**.** An aut
1ffc0 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
1ffd0 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
1ffe0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
1fff0 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
20000 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
20010 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
20020 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
20030 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
20040 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
20050 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
20060 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
20070 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
20080 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
20090 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
200a0 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
200b0 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
200c0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
200d0 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
200e0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
200f0 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
20100 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
20110 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
20120 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
20130 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
20140 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
20150 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
20160 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
20170 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
20180 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
20190 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
201a0 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
201b0 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
201c0 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
201d0 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
201e0 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
201f0 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
20200 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
20210 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
20220 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
20230 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
20240 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
20250 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
20260 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
20270 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
20280 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
20290 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
202a0 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
202b0 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
202c0 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
202d0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
202e0 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
202f0 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
20300 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
20310 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
20320 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
20330 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
20340 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79  er..**.** ^(Only
20350 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
20360 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
20370 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
20380 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
20390 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
203a0 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
203b0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
203c0 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
203d0 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
203e0 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65  )^  ^Disable the
203f0 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
20400 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
20410 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
20420 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
20430 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
20440 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
20450 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20460 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
20470 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
20480 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
20490 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
204a0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
204b0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
204c0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
204d0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
204e0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
204f0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
20500 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
20510 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
20520 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
20530 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
20540 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
20550 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
20560 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  * ^When [sqlite3
20570 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
20580 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
20590 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
205a0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
205b0 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
205c0 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
205d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
205e0 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
205f0 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
20600 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
20610 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
20620 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
20630 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
20640 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
20650 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
20660 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
20670 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ()]..**.** ^Note
20680 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
20690 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
206a0 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
206b0 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
206c0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
206d0 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
206e0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
206f0 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
20700 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
20710 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
20720 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
20730 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
20740 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
20750 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
20760 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
20770 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
20780 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
20790 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
207a0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
207b0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
207c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  /.int sqlite3_se
207d0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
207e0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
207f0 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
20800 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
20810 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
20820 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
20830 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
20840 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
20850 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
20860 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
20870 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
20880 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
20890 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
208a0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
208b0 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
208c0 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
208d0 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
208e0 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
208f0 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
20900 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
20910 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
20920 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
20930 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
20940 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
20950 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
20960 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
20970 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
20980 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
20990 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e  rmation..**.** N
209a0 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f  ote that SQLITE_
209b0 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75  IGNORE is also u
209c0 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69  sed as a [confli
209d0 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f  ct resolution mo
209e0 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  de].** returned 
209f0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
20a00 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
20a10 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ct()] interface.
20a20 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
20a30 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
20a40 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
20a50 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
20a60 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
20a70 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
20a80 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
20a90 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
20aa0 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
20ab0 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
20ac0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
20ad0 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
20ae0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
20af0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
20b00 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
20b10 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
20b20 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
20b30 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
20b40 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
20b50 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
20b60 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
20b70 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
20b80 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
20b90 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
20ba0 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
20bb0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
20bc0 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
20bd0 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
20be0 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
20bf0 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
20c00 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
20c10 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20c20 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
20c30 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
20c40 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
20c50 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
20c60 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
20c70 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
20c80 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
20c90 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
20ca0 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
20cb0 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
20cc0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
20cd0 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
20ce0 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
20cf0 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
20d00 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
20d10 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
20d20 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
20d30 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
20d40 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
20d50 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20d60 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
20d70 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
20d80 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
20d90 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
20da0 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
20db0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
20dc0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
20dd0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
20de0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
20df0 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
20e00 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
20e10 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
20e20 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
20e30 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
20e40 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
20e50 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
20e60 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
20e70 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
20e80 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
20e90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20ea0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
20eb0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
20ec0 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
20ed0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
20ee0 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
20ef0 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
20f00 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
20f10 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
20f20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
20f30 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
20f40 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
20f50 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
20f60 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20f70 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
20f80 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
20f90 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
20fa0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
20fb0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
20fc0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
20fd0 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
20fe0 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
20ff0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
21000 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21010 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
21020 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
21030 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
21040 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
21050 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21060 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21070 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
21080 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
21090 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
210a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
210b0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
210c0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
210d0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
210e0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
210f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21100 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
21110 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
21120 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
21130 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21140 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21150 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
21160 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
21170 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21180 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21190 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
211a0 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
211b0 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
211c0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
211d0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
211e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
211f0 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
21200 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
21210 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21220 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21230 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21240 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
21250 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
21260 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
21270 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21280 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21290 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
212a0 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
212b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
212c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
212d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
212e0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
212f0 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
21300 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
21310 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
21320 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21330 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
21340 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
21350 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
21360 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21370 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21380 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
21390 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
213a0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
213b0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
213c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
213d0 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
213e0 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
213f0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
21400 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21410 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
21420 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
21430 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
21440 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
21450 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21460 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
21470 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
21480 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
21490 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
214a0 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
214b0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
214c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
214d0 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
214e0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
214f0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
21500 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
21510 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
21520 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
21530 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
21540 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21550 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
21560 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
21570 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
21580 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21590 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
215a0 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
215b0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
215c0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
215d0 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
215e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
215f0 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
21600 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
21610 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
21620 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21630 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21640 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
21650 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
21660 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
21670 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21680 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21690 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
216a0 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
216b0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
216c0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
216d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
216e0 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
216f0 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
21700 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
21710 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21720 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21730 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
21740 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
21750 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21760 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21770 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21780 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
21790 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
217a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
217b0 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
217c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
217d0 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
217e0 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
217f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
21800 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
21810 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21820 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
21830 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
21840 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
21850 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
21860 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
21870 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
21880 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
21890 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
218a0 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
218b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
218c0 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
218d0 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
218e0 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65  nger used */.#de
218f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55  fine SQLITE_RECU
21900 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20  RSIVE           
21910 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   33   /* NULL   
21920 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
21930 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a           */../*.
21940 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
21950 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
21960 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ng Functions.** 
21970 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
21980 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
21990 69 6e 65 73 20 61 72 65 20 64 65 70 72 65 63 61  ines are depreca
219a0 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71  ted. Use the [sq
219b0 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
219c0 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  ] interface.** i
219d0 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f  nstead of the ro
219e0 75 74 69 6e 65 73 20 64 65 73 63 72 69 62 65 64  utines described
219f0 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   here..**.** The
21a00 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
21a10 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
21a20 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
21a30 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
21a40 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
21a50 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
21a60 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
21a70 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
21a80 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
21a90 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
21aa0 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
21ab0 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
21ac0 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
21ad0 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
21ae0 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
21af0 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
21b00 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
21b10 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
21b20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
21b30 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
21b40 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
21b50 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
21b60 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
21b70 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
21b80 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
21b90 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
21ba0 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
21bb0 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
21bc0 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
21bd0 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
21be0 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
21bf0 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
21c00 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
21c10 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
21c20 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
21c30 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
21c40 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
21c50 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
21c60 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
21c70 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
21c80 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
21c90 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68  d to limit.** th
21ca0 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75  e length of [bou
21cb0 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78  nd parameter] ex
21cc0 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f  pansion in the o
21cd0 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33  utput of sqlite3
21ce0 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  _trace()..**.** 
21cf0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
21d00 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
21d10 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
21d20 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
21d30 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
21d40 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
21d50 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
21d60 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
21d70 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
21d80 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
21d90 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
21da0 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
21db0 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
21dc0 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
21dd0 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
21de0 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
21df0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
21e00 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
21e10 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
21e20 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
21e30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
21e40 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
21e50 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
21e60 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
21e70 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
21e80 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
21e90 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
21ea0 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
21eb0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
21ec0 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
21ed0 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
21ee0 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
21ef0 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
21f00 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
21f10 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
21f20 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
21f30 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
21f40 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
21f50 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
21f60 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
21f70 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
21f80 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52  ..*/.SQLITE_DEPR
21f90 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c  ECATED void *sql
21fa0 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
21fb0 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54  e3*,.   void(*xT
21fc0 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
21fd0 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
21fe0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
21ff0 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TED void *sqlite
22000 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
22010 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
22020 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
22030 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
22040 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
22050 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22060 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76 65  F: SQL Trace Eve
22070 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  nt Codes.** KEYW
22080 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41  ORDS: SQLITE_TRA
22090 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  CE.**.** These c
220a0 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66  onstants identif
220b0 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65  y classes of eve
220c0 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  nts that can be 
220d0 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69  monitored.** usi
220e0 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
220f0 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63  trace_v2()] trac
22100 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20  ing logic.  The 
22110 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
22120 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  * to [sqlite3_tr
22130 61 63 65 5f 76 32 28 29 5d 20 69 73 20 61 6e 20  ace_v2()] is an 
22140 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f  OR-ed combinatio
22150 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  n of one or more
22160 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
22170 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20  wing constants. 
22180 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
22190 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63  ment to the trac
221a0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  e callback.** is
221b0 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
221c0 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e  owing constants.
221d0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69  .**.** New traci
221e0 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79  ng constants may
221f0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
22200 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
22210 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c  .** ^A trace cal
22220 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61  lback has four a
22230 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62  rguments: xCallb
22240 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a  ack(T,C,P,X)..**
22250 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74   ^The T argument
22260 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69   is one of the i
22270 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f 64 65  nteger type code
22280 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65  s above..** ^The
22290 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   C argument is a
222a0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
222b0 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73  text pointer pas
222c0 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a  sed in as the.**
222d0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
222e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
222f0 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65  ce_v2()]..** The
22300 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e   P and X argumen
22310 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20  ts are pointers 
22320 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64  whose meanings d
22330 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a  epend on T..**.*
22340 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
22350 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20  TE_TRACE_STMT]] 
22360 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
22370 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _STMT</dt>.** <d
22380 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41  d>^An SQLITE_TRA
22390 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b  CE_STMT callback
223a0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
223b0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
223c0 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62  ement.** first b
223d0 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e  egins running an
223e0 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74  d possibly at ot
223f0 68 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67  her times during
22400 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f   the.** executio
22410 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65  n of the prepare
22420 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63  d statement, suc
22430 68 20 61 73 20 61 74 20 74 68 65 20 73 74 61 72  h as at the star
22440 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69  t of each.** tri
22450 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e  gger subprogram.
22460 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
22470 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
22480 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
22490 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
224a0 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  he X argument is
224b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
224c0 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20  string which.** 
224d0 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65  is the unexpande
224e0 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68  d SQL text of th
224f0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
22500 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63  ment or an SQL c
22510 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20  omment .** that 
22520 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 69 6e  indicates the in
22530 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72  vocation of a tr
22540 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c  igger.  ^The cal
22550 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74  lback can comput
22560 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65  e.** the same te
22570 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  xt that would ha
22580 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ve been returned
22590 20 62 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b   by the legacy [
225a0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d  sqlite3_trace()]
225b0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79  .** interface by
225c0 20 75 73 69 6e 67 20 74 68 65 20 58 20 61 72 67   using the X arg
225d0 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67  ument when X beg
225e0 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e  ins with "--" an
225f0 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73  d invoking.** [s
22600 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
22610 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73  sql(P)] otherwis
22620 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
22630 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d  E_TRACE_PROFILE]
22640 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
22650 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a  CE_PROFILE</dt>.
22660 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54  ** <dd>^An SQLIT
22670 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20  E_TRACE_PROFILE 
22680 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65  callback provide
22690 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20  s approximately 
226a0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f  the same.** info
226b0 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72  rmation as is pr
226c0 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 5b 73  ovided by the [s
226d0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
226e0 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e  ] callback..** ^
226f0 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
22700 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
22710 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
22720 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a  tement] and the.
22730 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f  ** X argument po
22740 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74  ints to a 64-bit
22750 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
22760 73 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 20  s the estimated 
22770 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  of.** the number
22780 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74   of nanosecond t
22790 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64  hat the prepared
227a0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
227b0 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20  to run..** ^The 
227c0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f  SQLITE_TRACE_PRO
227d0 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73  FILE callback is
227e0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
227f0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  e statement fini
22800 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  shes..**.** [[SQ
22810 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d  LITE_TRACE_ROW]]
22820 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
22830 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  E_ROW</dt>.** <d
22840 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41  d>^An SQLITE_TRA
22850 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20  CE_ROW callback 
22860 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  is invoked whene
22870 76 65 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a  ver a prepared.*
22880 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65  * statement gene
22890 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72  rates a single r
228a0 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a  ow of result.  .
228b0 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  ** ^The P argume
228c0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
228d0 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
228e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
228f0 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e  the.** X argumen
22900 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a  t is unused..**.
22910 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
22920 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51  E_CLOSE]] <dt>SQ
22930 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
22940 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e  </dt>.** <dd>^An
22950 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c   SQLITE_TRACE_CL
22960 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  OSE callback is 
22970 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64  invoked when a d
22980 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
22990 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a  ction closes..**
229a0 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
229b0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
229c0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
229d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63  onnection] objec
229e0 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61  t.** and the X a
229f0 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65  rgument is unuse
22a00 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  d..** </dl>.*/.#
22a10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
22a20 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30  ACE_STMT       0
22a30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  x01.#define SQLI
22a40 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
22a50 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65      0x02.#define
22a60 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f   SQLITE_TRACE_RO
22a70 57 20 20 20 20 20 20 20 20 30 78 30 34 0a 23 64  W        0x04.#d
22a80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
22a90 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78  CE_CLOSE      0x
22aa0 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  08../*.** CAPI3R
22ab0 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f  EF: SQL Trace Ho
22ac0 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ok.** METHOD: sq
22ad0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
22ae0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
22af0 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72  2(D,M,X,P) inter
22b00 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
22b10 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a   trace callback.
22b20 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67  ** function X ag
22b30 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20  ainst [database 
22b40 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75  connection] D, u
22b50 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61  sing property ma
22b60 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74  sk M.** and cont
22b70 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20  ext pointer P.  
22b80 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61  ^If the X callba
22b90 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72  ck is.** NULL or
22ba0 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69   if the M mask i
22bb0 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61  s zero, then tra
22bc0 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64  cing is disabled
22bd0 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75  .  The.** M argu
22be0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
22bf0 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64  he bitwise OR-ed
22c00 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
22c10 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  ** zero or more 
22c20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63  [SQLITE_TRACE] c
22c30 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  onstants..**.** 
22c40 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69  ^Each call to ei
22c50 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ther sqlite3_tra
22c60 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  ce() or sqlite3_
22c70 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72  trace_v2() overr
22c80 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c  ides .** (cancel
22c90 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c  s) any prior cal
22ca0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72  ls to sqlite3_tr
22cb0 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ace() or sqlite3
22cc0 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a  _trace_v2()..**.
22cd0 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61  ** ^The X callba
22ce0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
22cf0 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68  enever any of th
22d00 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66  e events identif
22d10 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20  ied by .** mask 
22d20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69  M occur.  ^The i
22d30 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20 76 61  nteger return va
22d40 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c  lue from the cal
22d50 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74  lback is current
22d60 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74  ly.** ignored, t
22d70 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20 63  hough this may c
22d80 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
22d90 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62  releases.  Callb
22da0 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ack.** implement
22db0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65  ations should re
22dc0 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73  turn zero to ens
22dd0 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61  ure future compa
22de0 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
22df0 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ^A trace callbac
22e00 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
22e10 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73  h four arguments
22e20 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50  : callback(T,C,P
22e30 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61  ,X)..** ^The T a
22e40 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
22e50 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52  f the [SQLITE_TR
22e60 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74  ACE].** constant
22e70 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  s to indicate wh
22e80 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77  y the callback w
22e90 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e  as invoked..** ^
22ea0 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69  The C argument i
22eb0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
22ec0 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e  context pointer.
22ed0 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20  .** The P and X 
22ee0 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f  arguments are po
22ef0 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61  inters whose mea
22f00 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20  nings depend on 
22f10 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  T..**.** The sql
22f20 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20  ite3_trace_v2() 
22f30 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
22f40 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65  ended to replace
22f50 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
22f60 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
22f70 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20  e3_trace()] and 
22f80 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
22f90 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69  ()], both of whi
22fa0 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63  ch.** are deprec
22fb0 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ated..*/.int sql
22fc0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20  ite3_trace_v2(. 
22fd0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73   sqlite3*,.  uns
22fe0 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69  igned uMask,.  i
22ff0 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75  nt(*xCallback)(u
23000 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f  nsigned,void*,vo
23010 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  id*,void*),.  vo
23020 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a  id *pCtx.);../*.
23030 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
23040 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
23050 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  backs.** METHOD:
23060 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
23070 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
23080 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
23090 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
230a0 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
230b0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
230c0 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
230d0 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
230e0 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
230f0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
23100 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
23110 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23120 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
23130 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
23140 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
23150 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
23160 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
23170 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
23180 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
23190 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
231a0 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
231b0 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
231c0 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
231d0 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
231e0 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
231f0 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
23200 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
23210 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
23220 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65   the approximate
23230 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
23240 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
23250 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
23260 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
23270 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
23280 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
23290 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
232a0 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20  ck X.  ^If N is 
232b0 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68  less than one th
232c0 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a  en the progress.
232d0 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69  ** handler is di
232e0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  sabled..**.** ^O
232f0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
23300 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61  gress handler ma
23310 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20  y be defined at 
23320 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20  one time per.** 
23330 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
23340 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61  tion]; setting a
23350 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61   new progress ha
23360 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68  ndler cancels th
23370 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e  e.** old one.  ^
23380 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65  Setting paramete
23390 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61  r X to NULL disa
233a0 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73  bles the progres
233b0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54  s handler..** ^T
233c0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
233d0 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61  ler is also disa
233e0 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
233f0 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73  N to a value les
23400 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a  s.** than 1..**.
23410 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
23420 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
23430 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
23440 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
23450 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
23460 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
23470 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
23480 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
23490 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
234a0 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
234b0 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
234c0 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
234d0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  dler callback mu
234e0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
234f0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
23500 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
23510 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
23520 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
23530 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
23540 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
23550 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
23560 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
23570 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
23580 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
23590 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
235a0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
235b0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
235c0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
235d0 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  ph..**.*/.void s
235e0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
235f0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
23600 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
23610 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
23620 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
23630 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
23640 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
23650 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a  .** CONSTRUCTOR:
23660 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
23670 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
23680 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
23690 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
236a0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
236b0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
236c0 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
236d0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
236e0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
236f0 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
23700 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
23710 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
23720 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
23730 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
23740 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
23750 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
23760 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
23770 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
23780 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
23790 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
237a0 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
237b0 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
237c0 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
237d0 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
237e0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
237f0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
23800 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
23810 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
23820 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
23830 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
23840 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
23850 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
23860 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
23870 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
23880 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
23890 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
238a0 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
238b0 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
238c0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
238d0 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
238e0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
238f0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
23900 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
23910 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
23920 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
23930 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
23940 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
23950 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
23960 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
23970 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
23980 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
23990 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
239a0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
239b0 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
239c0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
239d0 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20  t encoding will 
239e0 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74  be UTF-8 for dat
239f0 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75  abases created u
23a00 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  sing.** sqlite3_
23a10 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
23a20 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54  3_open_v2().  ^T
23a30 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
23a40 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65  ing for database
23a50 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69  s.** created usi
23a60 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  ng sqlite3_open1
23a70 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  6() will be UTF-
23a80 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
23a90 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
23aa0 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
23ab0 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
23ac0 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
23ad0 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
23ae0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
23af0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
23b00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
23b10 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
23b20 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
23b30 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
23b40 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
23b50 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
23b60 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
23b70 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
23b80 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
23b90 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
23ba0 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
23bb0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
23bc0 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
23bd0 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
23be0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
23bf0 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
23c00 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
23c10 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
23c20 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
23c30 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
23c40 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
23c50 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
23c60 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
23c70 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
23c80 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
23c90 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
23ca0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
23cb0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
23cc0 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
23cd0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
23ce0 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  HE],.** [SQLITE_
23cf0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
23d00 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  E], and/or [SQLI
23d10 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
23d20 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
23d30 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
23d40 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
23d50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
23d60 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
23d70 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
23d80 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
23d90 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
23da0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
23db0 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
23dc0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
23dd0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
23de0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
23df0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
23e00 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
23e10 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
23e20 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
23e30 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
23e40 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
23e50 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
23e60 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
23e70 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
23e80 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
23e90 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
23ea0 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
23eb0 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
23ec0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
23ed0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
23ee0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
23ef0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
23f00 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
23f10 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
23f20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
23f30 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
23f40 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
23f50 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
23f60 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
23f70 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
23f80 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
23f90 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
23fa0 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
23fb0 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
23fc0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
23fd0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
23fe0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
23ff0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
24000 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
24010 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
24020 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
24030 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
24040 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69  shown above opti
24050 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
24060 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53  with other.** [S
24070 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
24080 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45  NLY | SQLITE_OPE
24090 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65  N_* bits].** the
240a0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
240b0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
240c0 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
240d0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
240e0 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
240f0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
24100 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
24110 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
24120 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
24130 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
24140 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
24150 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
24160 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
24170 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
24180 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
24190 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
241a0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
241b0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
241c0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
241d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
241e0 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
241f0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
24200 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
24210 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
24220 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
24230 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
24240 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
24250 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
24260 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
24270 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
24280 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
24290 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
242a0 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
242b0 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
242c0 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
242d0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
242e0 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
242f0 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
24300 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
24310 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
24320 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
24330 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
24340 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
24350 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
24360 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24370 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
24380 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
24390 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
243a0 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
243b0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
243c0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
243d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
243e0 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
243f0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
24400 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
24410 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
24420 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
24430 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
24440 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
24450 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24460 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
24470 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
24480 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
24490 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
244a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
244b0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
244c0 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
244d0 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
244e0 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
244f0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
24500 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
24510 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
24520 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
24530 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
24540 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
24550 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
24560 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
24570 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
24580 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
24590 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
245a0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
245b0 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
245c0 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
245d0 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
245e0 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
245f0 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
24600 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
24610 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
24620 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
24630 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
24640 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
24650 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
24660 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
24670 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
24680 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
24690 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
246a0 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
246b0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
246c0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
246d0 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
246e0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
246f0 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
24700 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
24710 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
24720 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
24730 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
24740 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
24750 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
24760 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
24770 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
24780 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  ed..**.** [[URI 
24790 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c  filenames in sql
247a0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68  ite3_open()]] <h
247b0 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c  3>URI Filenames<
247c0 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b  /h3>.**.** ^If [
247d0 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e  URI filename] in
247e0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
247f0 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65  enabled, and the
24800 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
24810 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74  nt.** begins wit
24820 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20  h "file:", then 
24830 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
24840 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
24850 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69   URI. ^URI.** fi
24860 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
24870 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
24880 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
24890 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
248a0 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20  s.** set in the 
248b0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
248c0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
248d0 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68  v2(), or if it h
248e0 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c  as.** been enabl
248f0 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e  ed globally usin
24900 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
24910 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e  NFIG_URI] option
24920 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71   with the.** [sq
24930 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
24940 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65  method or by the
24950 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
24960 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
24970 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20  ption..** As of 
24980 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
24990 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61  .7.7, URI filena
249a0 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
249b0 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a  n is turned off.
249c0 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62  ** by default, b
249d0 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ut future releas
249e0 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  es of SQLite mig
249f0 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69  ht enable URI fi
24a00 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70  lename.** interp
24a10 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61  retation by defa
24a20 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20  ult.  See "[URI 
24a30 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20  filenames]" for 
24a40 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
24a50 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
24a60 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61   URI filenames a
24a70 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64  re parsed accord
24a80 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e  ing to RFC 3986.
24a90 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e   ^If the URI con
24aa0 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68  tains an.** auth
24ab0 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d  ority, then it m
24ac0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e  ust be either an
24ad0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
24ae0 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20   the string .** 
24af0 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66  "localhost". ^If
24b00 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69   the authority i
24b10 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73  s not an empty s
24b20 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68  tring or "localh
24b30 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72  ost", an .** err
24b40 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74  or is returned t
24b50 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54  o the caller. ^T
24b60 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70  he fragment comp
24b70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20  onent of a URI, 
24b80 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20  if .** present, 
24b90 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
24ba0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
24bb0 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e  he path componen
24bc0 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20  t of the URI as 
24bd0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
24be0 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69  disk file.** whi
24bf0 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  ch contains the 
24c00 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68  database. ^If th
24c10 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69  e path begins wi
24c20 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74  th a '/' charact
24c30 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20  er, .** then it 
24c40 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
24c50 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  s an absolute pa
24c60 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  th. ^If the path
24c70 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20   does not begin 
24c80 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28  .** with a '/' (
24c90 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65  meaning that the
24ca0 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69   authority secti
24cb0 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  on is omitted fr
24cc0 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74  om the URI).** t
24cd0 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20  hen the path is 
24ce0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
24cf0 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20   relative path. 
24d00 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73  .** ^(On windows
24d10 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70  , the first comp
24d20 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f  onent of an abso
24d30 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73  lute path .** is
24d40 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69   a drive specifi
24d50 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a  cation (e.g. "C:
24d60 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f  ").)^.**.** [[co
24d70 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72  re URI query par
24d80 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65  ameters]].** The
24d90 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
24da0 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f   of a URI may co
24db0 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73  ntain parameters
24dc0 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70   that are interp
24dd0 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20  reted.** either 
24de0 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66  by SQLite itself
24df0 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c  , or by a [VFS |
24e00 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c   custom VFS impl
24e10 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  ementation]..** 
24e20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62  SQLite and its b
24e30 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20  uilt-in [VFSes] 
24e40 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a  interpret the.**
24e50 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79   following query
24e60 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a   parameters:.**.
24e70 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
24e80 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54  > <b>vfs</b>: ^T
24e90 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74  he "vfs" paramet
24ea0 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74  er may be used t
24eb0 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61  o specify the na
24ec0 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56  me of.**     a V
24ed0 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70  FS object that p
24ee0 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72  rovides the oper
24ef0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
24f00 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75  erface that shou
24f10 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65  ld.**     be use
24f20 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  d to access the 
24f30 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e  database file on
24f40 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20   disk. ^If this 
24f50 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
24f60 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79  .**     an empty
24f70 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61   string the defa
24f80 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69  ult VFS object i
24f90 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79  s used. ^Specify
24fa0 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a  ing an unknown.*
24fb0 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20  *     VFS is an 
24fc0 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74  error. ^If sqlit
24fd0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
24fe0 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73  used and the vfs
24ff0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
25000 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20    present, then 
25010 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65  the VFS specifie
25020 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20  d by the option 
25030 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65  takes precedence
25040 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65   over.**     the
25050 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
25060 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
25070 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
25080 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
25090 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65  *   <li> <b>mode
250a0 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65  </b>: ^(The mode
250b0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
250c0 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
250d0 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20  "ro", "rw",.**  
250e0 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65     "rwc", or "me
250f0 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e  mory". Attemptin
25100 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61  g to set it to a
25110 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69  ny other value i
25120 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f  s.**     an erro
25130 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66  r)^. .**     ^If
25140 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69   "ro" is specifi
25150 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  ed, then the dat
25160 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
25170 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a  for read-only .*
25180 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75  *     access, ju
25190 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51  st as if the [SQ
251a0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
251b0 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65  LY] flag had bee
251c0 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a  n set in the .**
251d0 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d       third argum
251e0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
251f0 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68  pen_v2(). ^If th
25200 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
25210 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20   set to .**     
25220 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64  "rw", then the d
25230 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
25240 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65  d for read-write
25250 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65   (but not create
25260 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  ) .**     access
25270 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f  , as if SQLITE_O
25280 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62  PEN_READWRITE (b
25290 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50  ut not SQLITE_OP
252a0 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a  EN_CREATE) had .
252b0 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e  **     been set.
252c0 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73   ^Value "rwc" is
252d0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
252e0 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20  etting both .** 
252f0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
25300 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51  READWRITE and SQ
25310 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
25320 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  .  ^If the mode 
25330 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
25340 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22   set to "memory"
25350 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e   then a pure [in
25360 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
25370 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61  ] that never rea
25380 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69  ds.**     or wri
25390 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73  tes from disk is
253a0 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e   used. ^It is an
253b0 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66   error to specif
253c0 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a  y a value for.**
253d0 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61       the mode pa
253e0 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20  rameter that is 
253f0 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65  less restrictive
25400 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69   than that speci
25410 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74  fied by.**     t
25420 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20  he flags passed 
25430 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72  in the third par
25440 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
25450 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
25460 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63  **   <li> <b>cac
25470 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63  he</b>: ^The cac
25480 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
25490 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
254a0 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a  r "shared" or.**
254b0 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20       "private". 
254c0 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22  ^Setting it to "
254d0 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76  shared" is equiv
254e0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
254f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49   the.**     SQLI
25500 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
25510 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66  CHE bit in the f
25520 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61  lags argument pa
25530 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73  ssed to.**     s
25540 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25550 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63  . ^Setting the c
25560 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74  ache parameter t
25570 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a  o "private" is .
25580 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e  **     equivalen
25590 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
255a0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
255b0 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a  VATECACHE bit..*
255c0 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65  *     ^If sqlite
255d0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
255e0 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63  sed and the "cac
255f0 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73  he" parameter is
25600 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20   present in.**  
25610 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d     a URI filenam
25620 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65  e, its value ove
25630 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76  rrides any behav
25640 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79  ior requested by
25650 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20   setting.**     
25660 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
25670 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49  ATECACHE or SQLI
25680 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
25690 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20  CHE flag..**.** 
256a0 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62   <li> <b>psow</b
256b0 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72  >: ^The psow par
256c0 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73  ameter indicates
256d0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
256e0 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65  the.**     [powe
256f0 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d  rsafe overwrite]
25700 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f   property does o
25710 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79  r does not apply
25720 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73   to the.**     s
25730 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20  torage media on 
25740 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61  which the databa
25750 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e  se file resides.
25760 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
25770 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65  nolock</b>: ^The
25780 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65   nolock paramete
25790 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71  r is a boolean q
257a0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a  uery parameter.*
257b0 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73  *     which if s
257c0 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65  et disables file
257d0 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c   locking in roll
257e0 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64  back journal mod
257f0 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20  es.  This.**    
25800 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61   is useful for a
25810 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62  ccessing a datab
25820 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73  ase on a filesys
25830 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  tem that does no
25840 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74  t.**     support
25850 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69   locking.  Cauti
25860 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f  on:  Database co
25870 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72  rruption might r
25880 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20  esult if two.** 
25890 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63      or more proc
258a0 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74  esses write to t
258b0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
258c0 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20   and any one of 
258d0 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f  those.**     pro
258e0 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f  cesses uses nolo
258f0 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  ck=1..**.**  <li
25900 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f  > <b>immutable</
25910 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62  b>: ^The immutab
25920 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  le parameter is 
25930 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a  a boolean query.
25940 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72  **     parameter
25950 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
25960 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
25970 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64  e file is stored
25980 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d   on.**     read-
25990 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68  only media.  ^Wh
259a0 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20  en immutable is 
259b0 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75  set, SQLite assu
259c0 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
259d0 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c      database fil
259e0 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  e cannot be chan
259f0 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70  ged, even by a p
25a00 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68  rocess with high
25a10 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c  er.**     privil
25a20 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ege, and so the 
25a30 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
25a40 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64  ed read-only and
25a50 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20   all locking.** 
25a60 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64      and change d
25a70 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61  etection is disa
25a80 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20  bled.  Caution: 
25a90 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75  Setting the immu
25aa0 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f  table.**     pro
25ab0 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62  perty on a datab
25ac0 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f  ase file that do
25ad0 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67  es in fact chang
25ae0 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20  e can result.** 
25af0 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74      in incorrect
25b00 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61   query results a
25b10 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  nd/or [SQLITE_CO
25b20 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a  RRUPT] errors..*
25b30 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20  *     See also: 
25b40 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d  [SQLITE_IOCAP_IM
25b50 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20  MUTABLE]..**    
25b60 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a     .** </ul>.**.
25b70 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  ** ^Specifying a
25b80 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65  n unknown parame
25b90 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79  ter in the query
25ba0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
25bb0 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a  URI is not an.**
25bc0 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20   error.  Future 
25bd0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
25be0 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74  te might underst
25bf0 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71  and additional q
25c00 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
25c10 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79  rs.  See "[query
25c20 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68   parameters with
25c30 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67   special meaning
25c40 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72   to SQLite]" for
25c50 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
25c60 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
25c70 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
25c80 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e   examples]] <h3>
25c90 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
25ca0 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  mples</h3>.**.**
25cb0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
25cc0 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20  1" align=center 
25cd0 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a  cellpadding=5>.*
25ce0 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66  * <tr><th> URI f
25cf0 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65  ilenames <th> Re
25d00 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  sults.** <tr><td
25d10 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c  > file:data.db <
25d20 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
25d30 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
25d40 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
25d50 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
25d60 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  y..** <tr><td> f
25d70 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
25d80 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20  ata.db<br>.**   
25d90 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68         file:///h
25da0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
25db0 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <br> .**       
25dc0 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68     file://localh
25dd0 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  ost/home/fred/da
25de0 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20  ta.db <br> <td> 
25df0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
25e00 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
25e10 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
25e20 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72  data.db"..** <tr
25e30 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72  ><td> file://dar
25e40 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f  kstar/home/fred/
25e50 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
25e60 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
25e70 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69  or. "darkstar" i
25e80 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a  s not a recogniz
25e90 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a  ed authority..**
25ea0 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22   <tr><td style="
25eb0 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72  white-space:nowr
25ec0 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  ap"> .**        
25ed0 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63    file:///C:/Doc
25ee0 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53  uments%20and%20S
25ef0 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73  ettings/fred/Des
25f00 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20  ktop/data.db.** 
25f10 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73      <td> Windows
25f20 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20   only: Open the 
25f30 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f  file "data.db" o
25f40 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70  n fred's desktop
25f50 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20   on drive.**    
25f60 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74        C:. Note t
25f70 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61  hat the %20 esca
25f80 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61  ping in this exa
25f90 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69  mple is not stri
25fa0 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  ctly .**        
25fb0 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70    necessary - sp
25fc0 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63  ace characters c
25fd0 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72  an be used liter
25fe0 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ally.**         
25ff0 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65   in URI filename
26000 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  s..** <tr><td> f
26010 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
26020 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74  =ro&cache=privat
26030 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  e <td> .**      
26040 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64      Open file "d
26050 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
26060 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
26070 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61   for read-only a
26080 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20  ccess..**       
26090 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66     Regardless of
260a0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
260b0 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64  shared-cache mod
260c0 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a  e is enabled by.
260d0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
260e0 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61  ult, use a priva
260f0 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72  te cache..** <tr
26100 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
26110 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66  /fred/data.db?vf
26120 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c  s=unix-dotfile <
26130 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  td>.**          
26140 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65  Open file "/home
26150 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20  /fred/data.db". 
26160 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20  Use the special 
26170 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c  VFS "unix-dotfil
26180 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  e".**          t
26190 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c  hat uses dot-fil
261a0 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70  es in place of p
261b0 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f  osix advisory lo
261c0 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cking..** <tr><t
261d0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
261e0 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74  mode=readonly <t
261f0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
26200 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f  An error. "reado
26210 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61  nly" is not a va
26220 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74  lid option for t
26230 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65  he "mode" parame
26240 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ter..** </table>
26250 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61  .**.** ^URI hexa
26260 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
26270 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61  equences (%HH) a
26280 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74  re supported wit
26290 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64  hin the path and
262a0 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  .** query compon
262b0 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41  ents of a URI. A
262c0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
262d0 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e  ape sequence con
262e0 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65  sists of a.** pe
262f0 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22  rcent sign - "%"
26300 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65   - followed by e
26310 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64  xactly two hexad
26320 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a  ecimal digits .*
26330 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20  * specifying an 
26340 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65  octet value. ^Be
26350 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72  fore the path or
26360 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
26370 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69  s of a.** URI fi
26380 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72  lename are inter
26390 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65  preted, they are
263a0 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
263b0 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a  TF-8 and all .**
263c0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
263d0 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65  ape sequences re
263e0 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67  placed by a sing
263f0 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69  le byte containi
26400 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73  ng the.** corres
26410 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49  ponding octet. I
26420 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67  f this process g
26430 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61  enerates an inva
26440 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  lid UTF-8 encodi
26450 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  ng,.** the resul
26460 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
26470 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
26480 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
26490 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
264a0 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
264b0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
264c0 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
264d0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
264e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75  te3_open_v2() mu
264f0 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
26500 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
26510 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
26520 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
26530 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
26540 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
26550 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
26560 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
26570 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
26580 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
26590 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  nto.** sqlite3_o
265a0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
265b0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
265c0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
265d0 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65  dows Runtime use
265e0 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d  rs:</b>  The tem
265f0 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79  porary directory
26600 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20   must be set.** 
26610 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
26620 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
26630 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
26640 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65  v2().  Otherwise
26650 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61  , various.** fea
26660 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69  tures that requi
26670 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65  re the use of te
26680 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61  mporary files ma
26690 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65  y fail..**.** Se
266a0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
266b0 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d  _temp_directory]
266c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
266d0 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
266e0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
266f0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
26700 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
26710 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
26720 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
26730 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
26740 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
26750 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
26760 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
26770 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
26780 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
26790 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
267a0 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
267b0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
267c0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
267d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
267e0 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
267f0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
26800 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
26810 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
26820 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
26830 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
26840 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
26850 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
26860 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
26870 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
26880 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
26890 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
268a0 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
268b0 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
268c0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
268d0 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20   Values For URI 
268e0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
268f0 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69   These are utili
26900 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65  ty routines, use
26910 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65  ful to VFS imple
26920 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74  mentations, that
26930 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65   check.** to see
26940 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66   if a database f
26950 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68  ile was a URI th
26960 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73  at contained a s
26970 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a  pecific query .*
26980 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64  * parameter, and
26990 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74   if so obtains t
269a0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  he value of that
269b0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
269c0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20  ..**.** If F is 
269d0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
269e0 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61  ename pointer pa
269f0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
26a00 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  pen() method of 
26a10 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d  .** a VFS implem
26a20 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68  entation when th
26a30 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
26a40 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73  r to xOpen() has
26a50 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65   one or .** more
26a60 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
26a70 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51  OPEN_URI] or [SQ
26a80 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
26a90 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a  B] bits set and.
26aa0 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65  ** P is the name
26ab0 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61   of the query pa
26ac0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a  rameter, then.**
26ad0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
26ae0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
26af0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rns the value of
26b00 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65   the P.** parame
26b10 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73  ter if it exists
26b20 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
26b30 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74  er if P does not
26b40 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a   appear as a .**
26b50 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
26b60 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20   on F.  If P is 
26b70 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  a query paramete
26b80 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f  r of F.** has no
26b90 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c   explicit value,
26ba0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
26bb0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
26bc0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f   returns.** a po
26bd0 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74  inter to an empt
26be0 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  y string..**.** 
26bf0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
26c00 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
26c10 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74  outine assumes t
26c20 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65  hat P is a boole
26c30 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  an.** parameter 
26c40 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65  and returns true
26c50 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30   (1) or false (0
26c60 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74  ) according to t
26c70 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50  he value.** of P
26c80 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  .  The sqlite3_u
26c90 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
26ca0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
26cb0 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68  s true (1) if th
26cc0 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75  e.** value of qu
26cd0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
26ce0 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c  is one of "yes",
26cf0 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22   "true", or "on"
26d00 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20   in any.** case 
26d10 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
26d20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f  begins with a no
26d30 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20  n-zero number.  
26d40 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  The .** sqlite3_
26d50 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
26d60 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  B) routines retu
26d70 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66  rns false (0) if
26d80 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a   the value of.**
26d90 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
26da0 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f   P is one of "no
26db0 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22  ", "false", or "
26dc0 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65  off" in any case
26dd0 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61   or.** if the va
26de0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
26df0 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20  a numeric zero. 
26e00 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71   If P is not a q
26e10 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
26e20 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65  r on F or if the
26e30 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64   value of P is d
26e40 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e  oes not match an
26e50 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76  y of the.** abov
26e60 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
26e70 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
26e80 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30  B) returns (B!=0
26e90 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
26ea0 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46  ite3_uri_int64(F
26eb0 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f  ,P,D) routine co
26ec0 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65  nverts the value
26ed0 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20   of P into a.** 
26ee0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
26ef0 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e  teger and return
26f00 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20  s that integer, 
26f10 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e  or D if P does n
26f20 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66  ot.** exist.  If
26f30 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
26f40 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  is something oth
26f50 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67  er than an integ
26f60 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f  er, then.** zero
26f70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
26f80 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e   .** If F is a N
26f90 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
26fa0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
26fb0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
26fc0 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a  urns NULL and.**
26fd0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
26fe0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
26ff0 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20  rns B.  If F is 
27000 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  not a NULL point
27010 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74  er and.** is not
27020 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
27030 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65   pathname pointe
27040 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61  r that SQLite pa
27050 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
27060 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f  pen.** VFS metho
27070 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
27080 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75  vior of this rou
27090 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65  tine is undefine
270a0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a  d and probably.*
270b0 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  * undesirable..*
270c0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
270d0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
270e0 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ter(const char *
270f0 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74  zFilename, const
27100 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a   char *zParam);.
27110 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  int sqlite3_uri_
27120 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68  boolean(const ch
27130 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74  ar *zFile, const
27140 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69   char *zParam, i
27150 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71  nt bDefault);.sq
27160 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
27170 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f  te3_uri_int64(co
27180 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74  nst char*, const
27190 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
271a0 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  int64);.../*.** 
271b0 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
271c0 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
271d0 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
271e0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lite3.**.** ^If 
271f0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
27200 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
27210 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ll associated wi
27220 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  th .** [database
27230 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66   connection] D f
27240 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ailed, then the 
27250 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
27260 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  D) interface.** 
27270 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
27280 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
27290 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72  ] or [extended r
272a0 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
272b0 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c  that.** API call
272c0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74  ..** If the most
272d0 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
272e0 20 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c   was successful,
272f0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
27300 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
27310 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
27320 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
27330 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
27340 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
27350 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
27360 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
27370 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
27380 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
27390 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
273a0 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
273b0 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
273c0 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
273d0 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
273e0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
273f0 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
27400 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
27410 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
27420 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
27430 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
27440 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
27450 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
27460 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
27470 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
27480 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
27490 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
274a0 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
274b0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
274c0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
274d0 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
274e0 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
274f0 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
27500 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
27510 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
27520 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
27530 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
27540 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
27550 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
27560 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
27570 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s.)^.**.** ^The 
27580 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29  sqlite3_errstr()
27590 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
275a0 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c  ns the English-l
275b0 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20  anguage text.** 
275c0 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
275d0 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  he [result code]
275e0 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e  , as UTF-8..** ^
275f0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
27600 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
27610 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
27620 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a  ged internally.*
27630 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62  * and must not b
27640 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61  e freed by the a
27650 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a  pplication)^..**
27660 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
27670 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
27680 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
27690 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
276a0 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
276b0 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
276c0 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
276d0 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
276e0 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
276f0 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
27700 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
27710 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
27720 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
27730 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
27740 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
27750 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
27760 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
27770 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
27780 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
27790 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
277a0 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
277b0 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
277c0 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
277d0 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
277e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
277f0 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
27800 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
27810 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
27820 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
27830 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
27840 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
27850 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
27860 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
27870 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
27880 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
27890 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
278a0 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
278b0 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
278c0 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
278d0 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
278e0 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
278f0 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
27900 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
27910 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
27920 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
27930 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
27940 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
27950 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
27960 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
27970 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
27980 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   set..*/.int sql
27990 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
279a0 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
279b0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
279c0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
279d0 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
279e0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
279f0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
27a00 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
27a10 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
27a20 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  *);.const char *
27a30 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69  sqlite3_errstr(i
27a40 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
27a50 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53  3REF: Prepared S
27a60 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
27a70 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
27a80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27a90 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
27aa0 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
27ab0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
27ac0 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
27ad0 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
27ae0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a   statement that.
27af0 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70  ** has been comp
27b00 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79  iled into binary
27b10 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61   form and is rea
27b20 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  dy to be evaluat
27b30 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20  ed..**.** Think 
27b40 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  of each SQL stat
27b50 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72  ement as a separ
27b60 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f  ate computer pro
27b70 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72  gram.  The.** or
27b80 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20  iginal SQL text 
27b90 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20  is source code. 
27ba0 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74   A prepared stat
27bb0 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a  ement object .**
27bc0 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64   is the compiled
27bd0 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41   object code.  A
27be0 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63  ll SQL must be c
27bf0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a  onverted into a.
27c00 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
27c10 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20  ement before it 
27c20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a  can be run..**.*
27c30 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65  * The life-cycle
27c40 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73   of a prepared s
27c50 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
27c60 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b  usually goes lik
27c70 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
27c80 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
27c90 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  e the prepared s
27ca0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
27cb0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
27cc0 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a  repare_v2()]..**
27cd0 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65   <li> Bind value
27ce0 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73  s to [parameters
27cf0 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
27d00 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
27d10 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
27d20 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
27d30 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
27d40 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
27d50 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
27d60 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
27d70 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
27d80 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
27d90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
27da0 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
27db0 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
27dc0 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
27dd0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
27de0 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
27df0 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
27e00 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
27e10 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f  ()]..** </ol>.*/
27e20 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
27e30 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
27e40 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
27e50 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
27e60 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d  time Limits.** M
27e70 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
27e80 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
27e90 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
27ea0 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
27eb0 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
27ec0 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
27ed0 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
27ee0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
27ef0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
27f00 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
27f10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
27f20 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
27f30 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
27f40 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
27f50 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
27f60 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
27f70 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
27f80 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
27f90 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
27fa0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
27fb0 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
27fc0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
27fd0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
27fe0 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
27ff0 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
28000 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
28010 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
28020 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
28030 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
28040 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
28050 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
28060 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
28070 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
28080 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
28090 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
280a0 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
280b0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
280c0 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
280d0 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
280e0 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
280f0 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
28100 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
28110 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
28120 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
28130 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
28140 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
28150 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
28160 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
28170 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
28180 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
28190 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
281a0 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
281b0 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
281c0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
281d0 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
281e0 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
281f0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
28200 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
28210 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
28220 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
28230 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
28240 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
28250 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
28260 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
28270 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
28280 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
28290 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
282a0 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
282b0 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
282c0 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
282d0 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
282e0 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
282f0 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
28300 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
28310 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
28320 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
28330 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
28340 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
28350 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
28360 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
28370 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
28380 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
28390 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
283a0 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
283b0 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
283c0 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
283d0 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
283e0 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
283f0 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
28400 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
28410 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
28420 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
28430 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
28440 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
28450 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
28460 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
28470 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
28480 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
28490 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
284a0 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
284b0 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
284c0 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
284d0 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
284e0 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
284f0 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
28500 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
28510 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
28520 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
28530 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
28540 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
28550 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
28560 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
28570 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
28580 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
28590 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
285a0 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
285b0 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
285c0 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
285d0 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
285e0 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
285f0 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
28600 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
28610 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
28620 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
28630 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
28640 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
28650 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
28660 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
28670 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
28680 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
28690 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
286a0 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
286b0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
286c0 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
286d0 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
286e0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
286f0 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
28700 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
28710 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
28720 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
28730 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
28740 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
28750 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
28760 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
28770 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
28780 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
28790 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
287a0 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
287b0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
287c0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d  E_LIMIT_LENGTH]]
287d0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
287e0 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
287f0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
28800 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
28810 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
28820 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62   table row, in b
28830 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a  ytes.<dd>)^.**.*
28840 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
28850 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  _SQL_LENGTH]] ^(
28860 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
28870 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
28880 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
28890 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
288a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
288b0 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e  in bytes.</dd>)^
288c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
288d0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e  LIMIT_COLUMN]] ^
288e0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
288f0 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
28900 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
28910 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
28920 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
28930 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
28940 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
28950 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
28960 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
28970 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
28980 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
28990 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
289a0 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
289b0 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  use.</dd>)^.**.*
289c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
289d0 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28  _EXPR_DEPTH]] ^(
289e0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
289f0 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
28a00 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
28a10 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
28a20 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
28a30 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
28a40 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
28a50 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
28a60 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c  UND_SELECT]] ^(<
28a70 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
28a80 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
28a90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
28aa0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
28ab0 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
28ac0 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
28ad0 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
28ae0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
28af0 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28  MIT_VDBE_OP]] ^(
28b00 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
28b10 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
28b20 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
28b30 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
28b40 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
28b50 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
28b60 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
28b70 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
28b80 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69   statement.  Thi
28b90 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  s limit is not c
28ba0 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f  urrently.** enfo
28bb0 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61  rced, though tha
28bc0 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64  t might be added
28bd0 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
28be0 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
28bf0 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  Lite.</dd>)^.**.
28c00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
28c10 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
28c20 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
28c30 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
28c40 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
28c50 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
28c60 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
28c70 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
28c80 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
28c90 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
28ca0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
28cb0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
28cc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
28cd0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
28ce0 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
28cf0 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
28d00 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
28d10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
28d20 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
28d30 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
28d40 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
28d50 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
28d60 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
28d70 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
28d80 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
28d90 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
28da0 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
28db0 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
28dc0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
28dd0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
28de0 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
28df0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
28e00 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
28e10 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
28e20 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
28e30 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
28e40 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
28e50 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
28e60 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
28e70 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
28e80 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
28e90 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
28ea0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
28eb0 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
28ec0 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
28ed0 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
28ee0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
28ef0 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
28f00 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51  READS]] ^(<dt>SQ
28f10 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
28f20 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a  R_THREADS</dt>.*
28f30 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
28f40 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69  m number of auxi
28f50 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72  liary worker thr
28f60 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67  eads that a sing
28f70 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  le.** [prepared 
28f80 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73  statement] may s
28f90 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  tart.</dd>)^.** 
28fa0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
28fb0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
28fc0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
28fd0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
28fe0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
28ff0 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
29000 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
29010 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29020 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
29030 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
29040 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29050 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
29060 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
29070 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29080 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
29090 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
290a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
290b0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
290c0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
290d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
290e0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
290f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
29100 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29110 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
29120 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
29130 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29140 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
29150 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
29160 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
29170 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
29180 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
29190 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
291a0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
291b0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
291c0 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
291d0 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
291e0 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20  THREADS         
291f0 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    11../*.** CAPI
29200 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
29210 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
29220 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
29230 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
29240 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  piler}.** METHOD
29250 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e  : sqlite3.** CON
29260 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
29270 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20  3_stmt.**.** To 
29280 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
29290 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
292a0 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
292b0 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
292c0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
292d0 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
292e0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
292f0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
29300 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
29310 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29320 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
29330 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
29340 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
29350 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
29360 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
29370 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
29380 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
29390 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
293a0 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
293b0 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
293c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
293d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
293e0 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
293f0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
29400 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
29410 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
29420 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
29430 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
29440 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
29450 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
29460 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
29470 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
29480 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
29490 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
294a0 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
294b0 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
294c0 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
294d0 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76  ument is negativ
294e0 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  e, then zSql is 
294f0 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
29500 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
29510 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
29520 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20  te is positive, 
29530 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a  then it is the.*
29540 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
29550 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
29560 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  .  ^If nByte is 
29570 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72  zero, then no pr
29580 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
29590 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64  ent is generated
295a0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
295b0 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68  er knows that th
295c0 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
295d0 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
295e0 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ted, then.** the
295f0 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65  re is a small pe
29600 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
29610 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61  age to passing a
29620 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
29630 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65  r that.** is the
29640 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
29650 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
29660 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
29670 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
29680 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a  -terminator..**.
29690 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
296a0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
296b0 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
296c0 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
296d0 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
296e0 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
296f0 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
29700 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
29710 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
29720 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
29730 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
29740 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
29750 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
29760 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
29770 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
29780 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
29790 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
297a0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
297b0 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
297c0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
297d0 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
297e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
297f0 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
29800 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
29810 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
29820 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
29830 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
29840 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
29850 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
29860 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
29870 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
29880 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
29890 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
298a0 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
298b0 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
298c0 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
298d0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
298e0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
298f0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
29900 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
29910 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
29920 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
29930 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
29940 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
29950 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
29960 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
29970 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
29980 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
29990 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
299a0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
299b0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
299c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
299d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
299e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
299f0 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
29a00 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
29a10 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
29a20 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
29a30 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
29a40 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
29a50 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
29a60 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
29a70 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
29a80 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
29a90 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
29aa0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
29ab0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
29ac0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
29ad0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
29ae0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
29af0 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
29b00 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
29b10 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
29b20 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
29b30 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
29b40 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
29b50 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
29b60 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
29b70 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
29b80 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
29b90 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
29ba0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
29bb0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
29bc0 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
29bd0 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
29be0 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
29bf0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
29c00 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
29c10 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
29c20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
29c30 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
29c40 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e  it again. As man
29c50 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58  y as [SQLITE_MAX
29c60 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a  _SCHEMA_RETRY].*
29c70 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f  * retries will o
29c80 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69  ccur before sqli
29c90 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73  te3_step() gives
29ca0 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20   up and returns 
29cb0 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c  an error..** </l
29cc0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
29cd0 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
29ce0 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
29cf0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
29d00 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
29d10 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
29d20 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
29d30 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
29d40 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
29d50 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
29d60 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
29d70 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
29d80 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
29d90 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
29da0 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
29db0 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
29dc0 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
29dd0 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
29de0 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
29df0 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
29e00 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
29e10 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
29e20 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
29e30 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
29e40 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
29e50 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
29e60 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
29e70 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
29e80 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
29e90 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
29ea0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
29eb0 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
29ec0 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
29ed0 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
29ee0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
29ef0 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
29f00 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
29f10 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
29f20 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
29f30 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
29f40 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
29f50 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
29f60 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
29f70 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
29f80 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
29f90 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
29fa0 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
29fb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
29fc0 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
29fd0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
29fe0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
29ff0 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
2a000 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
2a010 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
2a020 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
2a030 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
2a040 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
2a050 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
2a060 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
2a070 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
2a080 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
2a090 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
2a0a0 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
2a0b0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
2a0c0 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
2a0d0 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
2a0e0 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
2a0f0 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
2a100 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
2a110 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT3] compile-ti
2a120 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
2a130 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  bled..** </li>.*
2a140 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ol>.*/.int s
2a150 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
2a160 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2a170 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2a180 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2a190 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
2a1a0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2a1b0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2a1c0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
2a1d0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2a1e0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2a1f0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2a200 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2a210 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2a220 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2a230 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2a240 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2a250 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2a260 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2a270 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2a280 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2a290 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2a2a0 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
2a2b0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2a2c0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2a2d0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2a2e0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
2a2f0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2a300 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
2a310 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2a320 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2a330 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2a340 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2a350 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2a360 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2a370 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2a380 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2a390 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
2a3a0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2a3b0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2a3c0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2a3d0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2a3e0 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
2a3f0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2a400 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2a410 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2a420 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
2a430 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2a440 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
2a450 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2a460 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2a470 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2a480 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2a490 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2a4a0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2a4b0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2a4c0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2a4d0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
2a4e0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2a4f0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2a500 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2a510 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
2a520 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2a530 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
2a540 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2a550 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2a560 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2a570 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2a580 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2a590 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
2a5a0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2a5b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2a5c0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2a5d0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2a5e0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2a5f0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2a600 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2a610 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2a620 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
2a630 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2a640 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2a650 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2a660 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2a670 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53  EF: Retrieving S
2a680 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20  tatement SQL.** 
2a690 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2a6a0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2a6b0 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69  sqlite3_sql(P) i
2a6c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2a6d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2a6e0 63 6f 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d  copy of the UTF-
2a6f0 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  8.** SQL text us
2a700 65 64 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72  ed to create [pr
2a710 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a720 5d 20 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20  ] P if P was.** 
2a730 63 72 65 61 74 65 64 20 62 79 20 65 69 74 68 65  created by eithe
2a740 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2a750 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
2a760 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2a770 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  2()]..** ^The sq
2a780 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2a790 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  ql(P) interface 
2a7a0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2a7b0 72 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20  r to a UTF-8.** 
2a7c0 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
2a7d0 67 20 74 68 65 20 53 51 4c 20 74 65 78 74 20 6f  g the SQL text o
2a7e0 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
2a7f0 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b  ment P with.** [
2a800 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
2a810 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a  ] expanded..**.*
2a820 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2a830 20 69 66 20 61 20 70 72 65 70 61 72 65 64 20 73   if a prepared s
2a840 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72 65 61  tatement is crea
2a850 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ted using the SQ
2a860 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c 45 43  L.** text "SELEC
2a870 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64  T $abc,:xyz" and
2a880 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 24 61   if parameter $a
2a890 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f 20 69  bc is bound to i
2a8a0 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a 20 61  nteger 2345.** a
2a8b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a 78 79  nd parameter :xy
2a8c0 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68  z is unbound, th
2a8d0 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  en sqlite3_sql()
2a8e0 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
2a8f0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 72  the original str
2a900 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24 61 62  ing, "SELECT $ab
2a910 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71 6c 69  c,:xyz" but sqli
2a920 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2a930 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  ().** will retur
2a940 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35 2c 4e  n "SELECT 2345,N
2a950 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ULL".)^.**.** ^T
2a960 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  he sqlite3_expan
2a970 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65 72 66  ded_sql() interf
2a980 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ace returns NULL
2a990 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74   if insufficient
2a9a0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76   memory.** is av
2a9b0 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20  ailable to hold 
2a9c0 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72 20 69  the result, or i
2a9d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 77 6f 75  f the result wou
2a9e0 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a  ld exceed the.**
2a9f0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 74 72   the maximum str
2aa00 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74 65 72  ing length deter
2aa10 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b 53 51  mined by the [SQ
2aa20 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2aa30 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  H]..**.** ^The [
2aa40 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
2aa50 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
2aa60 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d  -time option lim
2aa70 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a  its the size of.
2aa80 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ** bound paramet
2aa90 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20  er expansions.  
2aaa0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  ^The [SQLITE_OMI
2aab0 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65  T_TRACE] compile
2aac0 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20  -time.** option 
2aad0 63 61 75 73 65 73 20 73 71 6c 69 74 65 33 5f 65  causes sqlite3_e
2aae0 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f  xpanded_sql() to
2aaf0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 4e   always return N
2ab00 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
2ab10 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20  string returned 
2ab20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50  by sqlite3_sql(P
2ab30 29 20 69 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ) is managed by 
2ab40 53 51 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a  SQLite and is.**
2ab50 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
2ab60 72 65 65 64 20 77 68 65 6e 20 74 68 65 20 70 72  reed when the pr
2ab70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ab80 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a   is finalized..*
2ab90 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65  * ^The string re
2aba0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2abb0 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50  3_expanded_sql(P
2abc0 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65 72 20  ), on the other 
2abd0 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61  hand,.** is obta
2abe0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
2abf0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
2ac00 20 6d 75 73 74 20 62 65 20 66 72 65 65 20 62 79   must be free by
2ac10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2ac20 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e 67 20 69  .** by passing i
2ac30 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  t to [sqlite3_fr
2ac40 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  ee()]..*/.const 
2ac50 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
2ac60 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
2ac70 70 53 74 6d 74 29 3b 0a 63 68 61 72 20 2a 73 71  pStmt);.char *sq
2ac80 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2ac90 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
2aca0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2acb0 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
2acc0 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
2acd0 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54  atement Writes T
2ace0 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d  he Database.** M
2acf0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2ad00 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
2ad10 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2ad20 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63  only(X) interfac
2ad30 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
2ad40 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20  non-zero) if.** 
2ad50 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
2ad60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ad70 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20  ent] X makes no 
2ad80 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74  direct changes t
2ad90 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  o.** the content
2ada0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2adb0 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74   file..**.** Not
2adc0 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74  e that [applicat
2add0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2ade0 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a  functions] or.**
2adf0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
2ae00 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  ] might change t
2ae10 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69  he database indi
2ae20 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65  rectly as a side
2ae30 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28   effect.  .** ^(
2ae40 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
2ae50 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
2ae60 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f  efines a functio
2ae70 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20  n "eval()" that 
2ae80 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74  .** calls [sqlit
2ae90 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e  e3_exec()], then
2aea0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
2aeb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75  QL statement wou
2aec0 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ld.** change the
2aed0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
2aee0 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65  hrough side-effe
2aef0 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  cts:.**.** <bloc
2af00 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
2af10 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27     SELECT eval('
2af20 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29  DELETE FROM t1')
2af30 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70   FROM t2;.** </p
2af40 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
2af50 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75  .**.** But becau
2af60 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  se the [SELECT] 
2af70 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
2af80 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ot change the da
2af90 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64  tabase file.** d
2afa0 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33  irectly, sqlite3
2afb0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2afc0 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74   would still ret
2afd0 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a  urn true.)^.**.*
2afe0 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63  * ^Transaction c
2aff0 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74  ontrol statement
2b000 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e  s such as [BEGIN
2b010 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f  ], [COMMIT], [RO
2b020 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56  LLBACK],.** [SAV
2b030 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45  EPOINT], and [RE
2b040 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c  LEASE] cause sql
2b050 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2b060 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
2b070 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68  rue,.** since th
2b080 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65  e statements the
2b090 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
2b0a0 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74  ctually modify t
2b0b0 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a  he database but.
2b0c0 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63  ** rather they c
2b0d0 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e  ontrol the timin
2b0e0 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20  g of when other 
2b0f0 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66  statements modif
2b100 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61  y the .** databa
2b110 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43  se.  ^The [ATTAC
2b120 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20  H] and [DETACH] 
2b130 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20  statements also 
2b140 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33  cause.** sqlite3
2b150 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2b160 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20   to return true 
2b170 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f  since, while tho
2b180 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  se statements.**
2b190 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66   change the conf
2b1a0 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64  iguration of a d
2b1b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b1c0 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  on, they do not 
2b1d0 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73  make .** changes
2b1e0 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   to the content 
2b1f0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2b200 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a  files on disk..*
2b210 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
2b220 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
2b230 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2b240 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b250 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2b260 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2b270 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
2b280 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  set.** METHOD: s
2b290 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2b2a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2b2b0 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65  tmt_busy(S) inte
2b2c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2b2d0 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
2b2e0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2b2f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
2b300 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20  as been stepped 
2b310 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73  at least once us
2b320 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
2b330 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61  _step(S)] but ha
2b340 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f  s neither run to
2b350 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74   completion (ret
2b360 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
2b370 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c  _DONE] from [sql
2b380 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e  ite3_step(S)]) n
2b390 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74  or.** been reset
2b3a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2b3b0 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65  reset(S)].  ^The
2b3c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2b3d0 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61  sy(S).** interfa
2b3e0 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  ce returns false
2b3f0 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20   if S is a NULL 
2b400 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69  pointer.  If S i
2b410 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c  s not a .** NULL
2b420 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20   pointer and is 
2b430 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  not a pointer to
2b440 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72   a valid [prepar
2b450 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2b460 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68   object, then th
2b470 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2b480 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
2b490 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
2b4a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2b4b0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2b4c0 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f  ed in combinatio
2b4d0 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  n [sqlite3_next_
2b4e0 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f  stmt()].** to lo
2b4f0 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65  cate all prepare
2b500 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73  d statements ass
2b510 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64  ociated with a d
2b520 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e  atabase .** conn
2b530 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20  ection that are 
2b540 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67  in need of being
2b550 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61   reset.  This ca
2b560 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f  n be used,.** fo
2b570 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69  r example, in di
2b580 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65  agnostic routine
2b590 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20  s to search for 
2b5a0 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61  prepared .** sta
2b5b0 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65  tements that are
2b5c0 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73   holding a trans
2b5d0 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a  action open..*/.
2b5e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
2b5f0 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74  _busy(sqlite3_st
2b600 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2b610 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c  I3REF: Dynamical
2b620 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
2b630 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
2b640 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
2b650 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
2b660 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2b670 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
2b680 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
2b690 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2b6a0 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
2b6b0 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
2b6c0 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
2b6d0 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
2b6e0 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
2b6f0 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
2b700 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
2b710 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20  ues it stores.  
2b720 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69  ^Values stored i
2b730 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
2b740 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62  objects.** can b
2b750 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61  e integers, floa
2b760 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2b770 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42  s, strings, BLOB
2b780 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  s, or NULL..**.*
2b790 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  * An sqlite3_val
2b7a0 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65  ue object may be
2b7b0 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74   either "protect
2b7c0 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63  ed" or "unprotec
2b7d0 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e  ted"..** Some in
2b7e0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
2b7f0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
2b800 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68  ite3_value.  Oth
2b810 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
2b820 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74   will accept eit
2b830 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20  her a protected 
2b840 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
2b850 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2b860 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66  .** Every interf
2b870 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73  ace that accepts
2b880 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61   sqlite3_value a
2b890 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69  rguments specifi
2b8a0 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72  es.** whether or
2b8b0 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73   not it requires
2b8c0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
2b8d0 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65  ite3_value.  The
2b8e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2b8f0 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66  ue_dup()] interf
2b900 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2b910 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e  to construct a n
2b920 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64  ew .** protected
2b930 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66   sqlite3_value f
2b940 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  rom an unprotect
2b950 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2b960 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
2b970 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
2b980 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
2b990 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
2b9a0 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
2b9b0 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
2b9c0 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
2b9d0 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
2b9e0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2b9f0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
2ba00 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
2ba10 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
2ba20 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2ba30 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
2ba40 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
2ba50 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
2ba60 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
2ba70 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
2ba80 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
2ba90 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
2baa0 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
2bab0 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
2bac0 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
2bad0 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
2bae0 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
2baf0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
2bb00 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
2bb10 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2bb20 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
2bb30 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
2bb40 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
2bb50 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
2bb60 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
2bb70 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2bb80 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
2bb90 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
2bba0 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
2bbb0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
2bbc0 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
2bbd0 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
2bbe0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
2bbf0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
2bc00 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
2bc10 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
2bc20 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
2bc30 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2bc40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2bc50 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
2bc60 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
2bc70 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
2bc80 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2bc90 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
2bca0 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
2bcb0 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
2bcc0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
2bcd0 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
2bce0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2bcf0 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
2bd00 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
2bd10 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2bd20 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
2bd30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2bd40 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
2bd50 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
2bd60 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2bd70 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2bd80 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
2bd90 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
2bda0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2bdb0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2bdc0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
2bdd0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
2bde0 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
2bdf0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
2be00 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
2be10 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
2be20 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
2be30 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2be40 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
2be50 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
2be60 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
2be70 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
2be80 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
2be90 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
2bea0 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
2beb0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
2bec0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
2bed0 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
2bee0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
2bef0 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
2bf00 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
2bf10 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
2bf20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
2bf30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
2bf40 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2bf50 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2bf60 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
2bf70 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2bf80 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2bf90 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
2bfa0 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
2bfb0 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
2bfc0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2bfd0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
2bfe0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
2bff0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
2c000 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2c010 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
2c020 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
2c030 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
2c040 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
2c050 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2c060 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
2c070 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
2c080 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
2c090 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2c0a0 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
2c0b0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
2c0c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
2c0d0 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
2c0e0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2c0f0 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
2c100 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
2c110 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2c120 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
2c130 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
2c140 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
2c150 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
2c160 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
2c170 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45  r binding}.** ME
2c180 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2c190 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  mt.**.** ^(In th
2c1a0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2c1b0 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73  text input to [s
2c1c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c1d0 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
2c1e0 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
2c1f0 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
2c200 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74  ed by a [paramet
2c210 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73  er] that matches
2c220 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e   one of followin
2c230 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a  g.** templates:.
2c240 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2c250 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
2c260 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
2c270 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
2c280 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
2c290 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
2c2a0 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62  the templates ab
2c2b0 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65  ove, NNN represe
2c2c0 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c  nts an integer l
2c2d0 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
2c2e0 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  VV represents an
2c2f0 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
2c300 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68  entifier.)^  ^Th
2c310 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
2c320 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
2c330 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
2c340 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
2c350 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
2c360 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
2c370 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
2c380 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2c390 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
2c3a0 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed here..**.** ^
2c3b0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2c3c0 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
2c3d0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2c3e0 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
2c3f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2c400 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
2c410 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2c420 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
2c430 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2c440 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
2c450 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
2c460 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2c470 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2c480 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
2c490 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65   be set..** ^The
2c4a0 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
2c4b0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
2c4c0 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65  ndex of 1.  ^Whe
2c4d0 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
2c4e0 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
2c4f0 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
2c500 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
2c510 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
2c520 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
2c530 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
2c540 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
2c550 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e  occurrence..** ^
2c560 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
2c570 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
2c580 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
2c590 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
2c5a0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2c5b0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
2c5c0 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e  I if desired.  ^
2c5d0 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
2c5e0 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
2c5f0 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
2c600 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20  of NNN..** ^The 
2c610 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
2c620 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
2c630 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
2c640 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
2c650 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
2c660 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
2c670 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
2c680 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  : 999)..**.** ^T
2c690 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2c6a0 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
2c6b0 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
2c6c0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
2c6d0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2c6e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2c6f0 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
2c700 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2c710 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  6().** or sqlite
2c720 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
2c730 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2c740 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2c750 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20  parameter.** is 
2c760 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20  ignored and the 
2c770 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68  end result is th
2c780 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65  e same as sqlite
2c790 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a  3_bind_null()..*
2c7a0 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
2c7b0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
2c7c0 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
2c7d0 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
2c7e0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2c7f0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2c800 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
2c810 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
2c820 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2c830 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
2c840 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
2c850 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
2c860 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2c870 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
2c880 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2c890 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2c8a0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2c8b0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
2c8c0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
2c8d0 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  hen the length o
2c8e0 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
2c8f0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2c900 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
2c910 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
2c920 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68  inator..** If th
2c930 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2c940 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2c950 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67  nd_blob() is neg
2c960 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74  ative, then.** t
2c970 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2c980 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
2c990 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66  a non-negative f
2c9a0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2c9b0 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  is provided to s
2c9c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2c9d0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2c9e0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f  _bind_text16() o
2c9f0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2ca00 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20  ext64() then.** 
2ca10 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d  that parameter m
2ca20 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
2ca30 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20  offset.** where 
2ca40 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
2ca50 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61  or would occur a
2ca60 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69  ssuming the stri
2ca70 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74  ng were NUL.** t
2ca80 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
2ca90 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
2caa0 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20  s occur at byte 
2cab0 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61  offsets less tha
2cac0 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n .** the value 
2cad0 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
2cae0 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65  rameter then the
2caf0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
2cb00 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20  g value will.** 
2cb10 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
2cb20 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75   NULs.  The resu
2cb30 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
2cb40 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69  s involving stri
2cb50 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65  ngs.** with embe
2cb60 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
2cb70 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2cb80 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2cb90 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e  t to the BLOB an
2cba0 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67  d string binding
2cbb0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2cbc0 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
2cbd0 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
2cbe0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
2cbf0 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
2cc00 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
2cc10 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
2cc20 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
2cc30 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
2cc40 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2cc50 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
2cc60 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69  f the call to bi
2cc70 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a  nd API fails..**
2cc80 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2cc90 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
2cca0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
2ccb0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
2ccc0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
2ccd0 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
2cce0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2ccf0 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
2cd00 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
2cd10 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
2cd20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
2cd30 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2cd40 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
2cd50 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
2cd60 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
2cd70 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
2cd80 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
2cd90 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
2cda0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
2cdb0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
2cdc0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
2cdd0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
2cde0 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  The sixth argume
2cdf0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
2ce00 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74  nd_text64() must
2ce10 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53   be one of.** [S
2ce20 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
2ce30 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51  LITE_UTF16], [SQ
2ce40 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f  LITE_UTF16BE], o
2ce50 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
2ce60 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79  E].** to specify
2ce70 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
2ce80 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65   the text in the
2ce90 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2cea0 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78  .  If.** the six
2ceb0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2cec0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2ced0 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  64() is not one 
2cee0 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65  of the.** allowe
2cef0 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61  d values shown a
2cf00 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20  bove, or if the 
2cf10 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73  text encoding is
2cf20 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72   different.** fr
2cf30 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  om the encoding 
2cf40 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2cf50 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
2cf60 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2cf70 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ior.** is undefi
2cf80 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2cf90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2cfa0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
2cfb0 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
2cfc0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
2cfd0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
2cfe0 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
2cff0 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
2d000 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
2d010 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
2d020 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
2d030 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
2d040 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
2d050 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
2d060 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
2d070 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
2d080 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
2d090 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
2d0a0 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
2d0b0 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
2d0c0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
2d0d0 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
2d0e0 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
2d0f0 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
2d100 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
2d110 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
2d120 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
2d130 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49  h BLOB..**.** ^I
2d140 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c  f any of the sql
2d150 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2d160 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2d170 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
2d180 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65  inter.** for the
2d190 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d1a0 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20  ment] or with a 
2d1b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d1c0 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20  nt for which.** 
2d1d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2d1e0 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
2d1f0 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74   more recently t
2d200 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  han [sqlite3_res
2d210 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  et()],.** then t
2d220 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74  he call will ret
2d230 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
2d240 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c  SE].  If any sql
2d250 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20  ite3_bind_().** 
2d260 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65  routine is passe
2d270 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  d a [prepared st
2d280 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2d290 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2d2a0 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  , the.** result 
2d2b0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
2d2c0 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75   probably harmfu
2d2d0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e  l..**.** ^Bindin
2d2e0 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
2d2f0 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
2d300 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
2d310 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64  ine..** ^Unbound
2d320 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2d330 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
2d340 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
2d350 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72  sqlite3_bind_* r
2d360 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
2d370 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
2d380 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b  ccess or an.** [
2d390 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
2d3a0 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
2d3b0 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  ng..** ^[SQLITE_
2d3c0 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65  TOOBIG] might be
2d3d0 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
2d3e0 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e   size of a strin
2d3f0 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63  g or BLOB.** exc
2d400 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f  eeds limits impo
2d410 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
2d420 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
2d430 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72  IMIT_LENGTH]) or
2d440 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f  .** [SQLITE_MAX_
2d450 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51  LENGTH]..** ^[SQ
2d460 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
2d470 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
2d480 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
2d490 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
2d4a0 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d  e.  ^[SQLITE_NOM
2d4b0 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
2d4c0 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
2d4d0 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
2d4e0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2d4f0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2d500 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2d510 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2d520 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
2d530 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2d540 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2d550 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
2d560 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
2d570 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2d580 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
2d590 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2d5a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2d5b0 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  d_blob64(sqlite3
2d5c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2d5d0 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  st void*, sqlite
2d5e0 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
2d5f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d600 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
2d610 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2d620 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
2d630 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
2d640 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69  ouble);.int sqli
2d650 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
2d660 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2d670 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
2d680 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
2d690 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2d6a0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
2d6b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2d6c0 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
2d6d0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74  stmt*, int);.int
2d6e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2d6f0 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
2d700 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
2d710 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69  ,int,void(*)(voi
2d720 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
2d730 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
2d740 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2d750 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2d760 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
2d770 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
2d780 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c  _bind_text64(sql
2d790 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2d7a0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
2d7b0 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20  lite3_uint64,.  
2d7c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d7d0 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
2d7e0 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20  oid*), unsigned 
2d7f0 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a  char encoding);.
2d800 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2d810 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2d820 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2d830 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
2d840 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2d850 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
2d860 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2d870 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69  int n);.int sqli
2d880 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2d890 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  b64(sqlite3_stmt
2d8a0 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
2d8b0 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20  uint64);../*.** 
2d8c0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2d8d0 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
2d8e0 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  rs.** METHOD: sq
2d8f0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2d900 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
2d910 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
2d920 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
2d930 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
2d940 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
2d950 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2d960 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
2d970 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
2d980 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
2d990 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
2d9a0 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
2d9b0 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
2d9c0 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
2d9d0 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
2d9e0 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
2d9f0 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
2da00 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
2da10 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
2da20 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ime..**.** ^(Thi
2da30 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
2da40 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
2da50 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
2da60 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
2da70 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
2da80 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
2da90 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
2daa0 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
2dab0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2dac0 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
2dad0 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
2dae0 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
2daf0 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a  form are used,.*
2db00 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
2db10 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
2db20 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
2db30 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2db40 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2db50 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2db60 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2db70 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
2db80 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2db90 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2dba0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2dbb0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2dbc0 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
2dbd0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2dbe0 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
2dbf0 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
2dc00 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  r.** METHOD: sql
2dc10 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2dc20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2dc30 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2dc40 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (P,N) interface 
2dc50 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2dc60 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20  ame of the N-th 
2dc70 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
2dc80 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
2dc90 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
2dca0 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65  * ^(SQL paramete
2dcb0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
2dcc0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2dcd0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2dce0 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
2dcf0 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
2dd00 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
2dd10 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2dd20 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
2dd30 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
2dd40 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2dd50 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
2dd60 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
2dd70 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
2dd80 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
2dd90 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50  he name.)^.** ^P
2dda0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2ddb0 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
2ddc0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
2ddd0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
2dde0 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65  me.** and are re
2ddf0 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61  ferred to as "na
2de00 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e  meless" or "anon
2de10 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
2de20 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  "..**.** ^The fi
2de30 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
2de40 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
2de50 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
2de60 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
2de70 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
2de80 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74  ge or if the N-t
2de90 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
2dea0 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
2deb0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
2dec0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  d.  ^The returne
2ded0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
2dee0 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
2def0 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
2df00 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
2df10 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
2df20 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
2df30 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
2df40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2df50 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2df60 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2df70 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2df80 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2df90 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2dfa0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2dfb0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2dfc0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2dfd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2dfe0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2dff0 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
2e000 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
2e010 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2e020 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e030 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2e040 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
2e050 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
2e060 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20  A Given Name.** 
2e070 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2e080 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  stmt.**.** ^Retu
2e090 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
2e0a0 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
2e0b0 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
2e0c0 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
2e0d0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
2e0e0 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
2e0f0 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
2e100 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
2e110 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2e120 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2e130 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
2e140 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2e150 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
2e160 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
2e170 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
2e180 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
2e190 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
2e1a0 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
2e1b0 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
2e1c0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
2e1d0 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
2e1e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
2e1f0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
2e200 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2e210 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2e220 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2e230 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2e240 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2e250 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
2e260 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2e270 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a  ameter_name()]..
2e280 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2e290 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2e2a0 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
2e2b0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
2e2c0 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
2e2d0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
2e2e0 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
2e2f0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2e300 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  nt.** METHOD: sq
2e310 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2e320 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
2e330 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
2e340 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
2e350 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
2e360 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
2e370 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2e380 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
2e390 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e3a0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
2e3b0 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
2e3c0 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
2e3d0 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
2e3e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e3f0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
2e400 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2e410 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e420 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
2e430 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
2e440 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
2e450 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2e460 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
2e470 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2e480 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
2e490 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2e4a0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2e4b0 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20  atement]. ^This 
2e4c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2e4d0 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
2e4e0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
2e4f0 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
2e500 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
2e510 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
2e520 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ATE])..**.** See
2e530 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2e540 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  data_count()].*/
2e550 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2e560 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
2e570 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2e580 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e590 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
2e5a0 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2e5b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2e5c0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2e5d0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2e5e0 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
2e5f0 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
2e600 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
2e610 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
2e620 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
2e630 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
2e640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2e650 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
2e660 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2e670 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
2e680 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
2e690 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
2e6a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2e6b0 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
2e6c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2e6d0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
2e6e0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
2e6f0 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
2e700 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
2e710 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2e720 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
2e730 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
2e740 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
2e750 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2e760 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
2e770 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
2e780 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
2e790 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
2e7a0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2e7b0 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
2e7c0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
2e7d0 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
2e7e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2e7f0 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
2e800 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
2e810 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
2e820 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2e830 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
2e840 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
2e850 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2e860 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2e870 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
2e880 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
2e890 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
2e8a0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
2e8b0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
2e8c0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2e8d0 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
2e8e0 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
2e8f0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
2e900 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
2e910 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
2e920 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
2e930 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
2e940 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
2e950 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
2e960 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
2e970 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
2e980 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
2e990 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2e9a0 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
2e9b0 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
2e9c0 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
2e9d0 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
2e9e0 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
2e9f0 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
2ea00 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
2ea10 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
2ea20 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
2ea30 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
2ea40 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
2ea50 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
2ea60 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
2ea70 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
2ea80 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74  e next..*/.const
2ea90 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2eaa0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
2eab0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2eac0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2ead0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2eae0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2eaf0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
2eb00 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
2eb10 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
2eb20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20  Query Result.** 
2eb30 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2eb40 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
2eb50 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
2eb60 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
2eb70 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
2eb80 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2eb90 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
2eba0 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
2ebb0 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
2ebc0 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
2ebd0 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
2ebe0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
2ebf0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
2ec00 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
2ec10 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
2ec20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
2ec30 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
2ec40 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
2ec50 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
2ec60 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
2ec70 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
2ec80 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
2ec90 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
2eca0 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
2ecb0 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
2ecc0 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
2ecd0 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
2ece0 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
2ecf0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2ed00 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
2ed10 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2ed20 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
2ed30 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
2ed40 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2ed50 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
2ed60 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2ed70 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
2ed80 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
2ed90 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
2eda0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2edb0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2edc0 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
2edd0 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
2ede0 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
2edf0 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
2ee00 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
2ee10 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
2ee20 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
2ee30 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
2ee40 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
2ee50 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
2ee60 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2ee70 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2ee80 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2ee90 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
2eea0 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
2eeb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2eec0 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
2eed0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
2eee0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
2eef0 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
2ef00 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2ef10 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
2ef20 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
2ef30 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
2ef40 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
2ef50 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
2ef60 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
2ef70 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
2ef80 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
2ef90 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
2efa0 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
2efb0 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
2efc0 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
2efd0 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
2efe0 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
2eff0 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
2f000 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2f010 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
2f020 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
2f030 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
2f040 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
2f050 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2f060 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
2f070 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
2f080 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
2f090 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
2f0a0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2f0b0 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
2f0c0 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
2f0d0 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
2f0e0 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
2f0f0 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
2f100 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
2f110 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
2f120 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
2f130 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
2f140 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
2f150 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
2f160 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2f170 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
2f180 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
2f190 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
2f1a0 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
2f1b0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
2f1c0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
2f1d0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
2f1e0 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
2f1f0 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
2f200 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2f210 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2f220 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
2f230 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
2f240 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
2f250 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f260 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
2f270 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
2f280 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2f290 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
2f2a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
2f2b0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
2f2c0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
2f2d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2f2e0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2f2f0 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
2f300 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
2f310 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
2f320 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f330 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
2f340 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
2f350 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2f360 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2f370 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
2f380 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2f390 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2f3a0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2f3b0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2f3c0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2f3d0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2f3e0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2f3f0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
2f400 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2f410 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
2f420 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2f430 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2f440 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2f450 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
2f460 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2f470 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2f480 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
2f490 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2f4a0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2f4b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2f4c0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2f4d0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2f4e0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
2f4f0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
2f500 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
2f510 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d  uery Result.** M
2f520 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2f530 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  tmt.**.** ^(The 
2f540 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2f550 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2f560 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
2f570 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
2f580 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
2f590 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
2f5a0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2f5b0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
2f5c0 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
2f5d0 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
2f5e0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
2f5f0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2f600 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
2f610 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
2f620 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
2f630 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
2f640 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
2f650 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2f660 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2f670 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
2f680 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
2f690 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
2f6a0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
2f6b0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
2f6c0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
2f6d0 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
2f6e0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
2f6f0 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
2f700 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
2f710 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
2f720 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
2f730 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
2f740 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
2f750 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
2f760 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
2f770 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
2f780 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
2f790 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
2f7a0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
2f7b0 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
2f7c0 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
2f7d0 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
2f7e0 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
2f7f0 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
2f800 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
2f810 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
2f820 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
2f830 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
2f840 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
2f850 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
2f860 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
2f870 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
2f880 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
2f890 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
2f8a0 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
2f8b0 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
2f8c0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
2f8d0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2f8e0 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
2f8f0 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
2f900 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
2f910 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
2f920 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
2f930 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
2f940 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
2f950 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
2f960 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
2f970 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
2f980 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63  ose values..*/.c
2f990 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2f9a0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
2f9b0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
2f9c0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2f9d0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2f9e0 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
2f9f0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2fa00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2fa10 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
2fa20 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d  L Statement.** M
2fa30 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2fa40 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  tmt.**.** After 
2fa50 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2fa60 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
2fa70 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65  prepared using e
2fa80 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
2fa90 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2faa0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2fab0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f  are16_v2()] or o
2fac0 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
2fad0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
2fae0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2faf0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2fb00 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
2fb10 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
2fb20 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
2fb30 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
2fb40 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
2fb50 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
2fb60 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
2fb70 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
2fb80 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
2fb90 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
2fba0 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
2fbb0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
2fbc0 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
2fbd0 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
2fbe0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
2fbf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2fc00 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
2fc10 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2fc20 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
2fc30 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2fc40 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
2fc50 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
2fc60 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2fc70 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
2fc80 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
2fc90 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
2fca0 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
2fcb0 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
2fcc0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
2fcd0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
2fce0 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
2fcf0 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  orted..**.** ^In
2fd00 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2fd10 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
2fd20 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
2fd30 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
2fd40 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
2fd50 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
2fd60 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
2fd70 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
2fd80 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69  _MISUSE]..** ^Wi
2fd90 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
2fda0 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
2fdb0 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
2fdc0 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
2fdd0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
2fde0 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
2fdf0 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
2fe00 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42  **.** ^[SQLITE_B
2fe10 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
2fe20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
2fe30 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
2fe40 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
2fe50 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
2fe60 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
2fe70 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65  ts job.  ^If the
2fe80 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2fe90 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
2fea0 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
2feb0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
2fec0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
2fed0 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
2fee0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
2fef0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
2ff00 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
2ff10 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
2ff20 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69  thin an.** expli
2ff30 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
2ff40 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
2ff50 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
2ff60 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
2ff70 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
2ff80 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
2ff90 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
2ffa0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
2ffb0 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
2ffc0 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
2ffd0 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
2ffe0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
2fff0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
30000 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
30010 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
30020 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
30030 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
30040 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
30050 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
30060 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
30070 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
30080 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
30090 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
300a0 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
300b0 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
300c0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
300d0 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
300e0 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
300f0 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
30100 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
30110 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
30120 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
30130 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
30140 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
30150 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
30160 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
30170 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
30180 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
30190 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
301a0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
301b0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
301c0 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
301d0 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
301e0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
301f0 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
30200 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
30210 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
30220 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
30230 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
30240 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
30250 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
30260 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
30270 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
30280 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
30290 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
302a0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
302b0 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
302c0 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
302d0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
302e0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
302f0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
30300 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
30310 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
30320 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
30330 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
30340 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
30350 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
30360 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
30370 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
30380 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
30390 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
303a0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
303b0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
303c0 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
303d0 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
303e0 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
303f0 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
30400 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
30410 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
30420 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
30430 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30440 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
30450 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
30460 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
30470 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
30480 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
30490 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
304a0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
304b0 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
304c0 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
304d0 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
304e0 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
304f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30500 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
30510 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
30520 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
30530 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
30540 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
30550 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
30560 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
30570 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
30580 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a  23.1, a call to.
30590 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
305a0 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65  t()] was require
305b0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
305c0 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20  step() returned 
305d0 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65  anything.** othe
305e0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
305f0 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73  OW] before any s
30600 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
30610 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  tion of.** sqlit
30620 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c  e3_step().  Fail
30630 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65  ure to reset the
30640 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
30650 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ent using .** [s
30660 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
30670 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  would result in 
30680 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  an [SQLITE_MISUS
30690 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a  E] return from.*
306a0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
306b0 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72  .  But after ver
306c0 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73  sion 3.6.23.1, s
306d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65  qlite3_step() be
306e0 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b  gan.** calling [
306f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
30700 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
30710 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61  n this circumsta
30720 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68  nce rather.** th
30730 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  an returning [SQ
30740 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54  LITE_MISUSE].  T
30750 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69  his is not consi
30760 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62  dered a compatib
30770 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62  ility.** break b
30780 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69  ecause any appli
30790 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72  cation that ever
307a0 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c   receives an SQL
307b0 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72  ITE_MISUSE error
307c0 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79  .** is broken by
307d0 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
307e0 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
307f0 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c  UTORESET] compil
30800 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a  e-time option.**
30810 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
30820 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61  restore the lega
30830 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  cy behavior..**.
30840 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
30850 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
30860 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
30870 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
30880 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
30890 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
308a0 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
308b0 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
308c0 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
308d0 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
308e0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
308f0 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
30900 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
30910 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
30920 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
30930 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
30940 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
30950 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
30960 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
30970 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
30980 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
30990 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
309a0 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
309b0 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
309c0 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
309d0 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
309e0 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
309f0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
30a00 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
30a10 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
30a20 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
30a30 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
30a40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
30a50 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
30a60 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
30a70 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
30a80 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
30a90 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
30aa0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30ab0 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
30ac0 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
30ad0 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
30ae0 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
30af0 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
30b00 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
30b10 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
30b20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
30b30 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
30b40 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nded..*/.int sql
30b50 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
30b60 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
30b70 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
30b80 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
30b90 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20  a result set.** 
30ba0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
30bb0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
30bc0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
30bd0 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  nt(P) interface 
30be0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
30bf0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
30c00 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
30c10 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
30c20 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
30c30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
30c40 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64  .** ^If prepared
30c50 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65   statement P doe
30c60 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c  s not have resul
30c70 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  ts ready to retu
30c80 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73  rn.** (via calls
30c90 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
30ca0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71  _column_int | sq
30cb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29  lite3_column_*()
30cc0 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ] of.** interfac
30cd0 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  es) then sqlite3
30ce0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
30cf0 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68  eturns 0..** ^Th
30d00 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
30d10 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
30d20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69  also returns 0 i
30d30 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f P is a NULL po
30d40 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73  inter..** ^The s
30d50 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
30d60 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74  t(P) routine ret
30d70 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72  urns 0 if the pr
30d80 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a  evious call to.*
30d90 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  * [sqlite3_step]
30da0 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51  (P) returned [SQ
30db0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68  LITE_DONE].  ^Th
30dc0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
30dd0 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20  ount(P).** will 
30de0 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20  return non-zero 
30df0 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  if previous call
30e00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
30e10 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a  p](P) returned.*
30e20 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  * [SQLITE_ROW], 
30e30 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61  except in the ca
30e40 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d  se of the [PRAGM
30e50 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61  A incremental_va
30e60 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69  cuum].** where i
30e70 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
30e80 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68   zero since each
30e90 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75   step of that mu
30ea0 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67  lti-step.** prag
30eb0 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c  ma returns 0 col
30ec0 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a  umns of data..**
30ed0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
30ee0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
30ef0 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
30f00 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
30f10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
30f20 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
30f30 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
30f40 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
30f50 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
30f60 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
30f70 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
30f80 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
30f90 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
30fa0 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
30fb0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
30fc0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
30fd0 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
30fe0 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
30ff0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
31000 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
31010 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
31020 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
31030 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
31040 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
31050 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
31060 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
31070 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
31080 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
31090 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
310a0 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
310b0 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
310c0 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
310d0 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
310e0 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
310f0 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
31100 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
31110 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
31120 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
31130 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
31140 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
31150 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
31160 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
31170 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
31180 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
31190 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
311a0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
311b0 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
311c0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
311d0 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
311e0 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
311f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
31200 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
31210 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
31220 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
31230 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
31240 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
31250 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
31260 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
31270 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
31280 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
31290 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
312a0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
312b0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
312c0 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
312d0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
312e0 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
312f0 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
31300 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
31310 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
31320 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
31330 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
31340 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
31350 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
31360 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
31370 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
31380 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
31390 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
313a0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
313b0 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
313c0 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
313d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
313e0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
313f0 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
31400 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
31410 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
31420 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
31430 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
31440 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
31450 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
31460 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
31470 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
31480 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
31490 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
314a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
314b0 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
314c0 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
314d0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
314e0 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
314f0 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
31500 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
31510 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
31520 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
31530 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
31540 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
31550 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
31560 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
31570 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
31580 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
31590 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
315a0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
315b0 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
315c0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
315d0 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
315e0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
315f0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
31600 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
31610 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
31620 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
31630 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
31640 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
31650 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
31660 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
31670 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
31680 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
31690 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
316a0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
316b0 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
316c0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
316d0 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
316e0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
316f0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
31700 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
31710 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
31720 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
31730 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
31740 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
31750 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
31760 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
31770 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
31780 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
31790 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
317a0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
317b0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
317c0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
317d0 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
317e0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
317f0 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
31800 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
31810 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
31820 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
31830 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
31840 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
31850 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
31860 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
31870 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
31880 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
31890 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
318a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
318b0 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
318c0 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
318d0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
318e0 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
318f0 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
31900 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
31910 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
31920 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
31930 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
31940 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
31950 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
31960 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
31970 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
31980 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
31990 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
319a0 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
319b0 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
319c0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
319d0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
319e0 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
319f0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
31a00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31a10 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
31a20 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
31a30 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
31a40 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
31a50 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
31a60 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
31a70 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
31a80 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
31a90 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
31aa0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
31ab0 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
31ac0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
31ad0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
31ae0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
31af0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
31b00 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
31b10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
31b20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
31b30 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
31b40 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
31b50 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
31b60 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
31b70 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
31b80 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
31b90 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
31ba0 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
31bb0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
31bc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
31bd0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
31be0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
31bf0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
31c00 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
31c10 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
31c20 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
31c30 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
31c40 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
31c50 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
31c60 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
31c70 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
31c80 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
31c90 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
31ca0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
31cb0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
31cc0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
31cd0 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
31ce0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
31cf0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
31d00 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
31d10 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
31d20 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
31d30 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
31d40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
31d50 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
31d60 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
31d70 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
31d80 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
31d90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
31da0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
31db0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
31dc0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
31dd0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
31de0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
31df0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
31e00 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
31e10 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
31e20 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
31e30 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
31e40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
31e50 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
31e60 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
31e70 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
31e80 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
31e90 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
31ea0 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
31eb0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
31ec0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31ed0 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
31ee0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31ef0 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
31f00 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
31f10 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
31f20 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
31f30 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
31f40 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
31f50 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
31f60 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
31f70 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
31f80 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
31f90 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
31fa0 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
31fb0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
31fc0 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
31fd0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
31fe0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
31ff0 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
32000 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
32010 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
32020 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e   <b>Warning:</b>
32030 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
32040 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
32050 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
32060 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
32070 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
32080 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
32090 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64  In a multithread
320a0 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a  ed environment,.
320b0 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  ** an unprotecte
320c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
320d0 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20  object may only 
320e0 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77  be used safely w
320f0 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
32100 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
32110 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
32120 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
32130 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
32140 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32150 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
32160 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
32170 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
32180 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
32190 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
321a0 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
321b0 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
321c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
321d0 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
321e0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
321f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
32200 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
32210 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74   behavior is not
32220 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a   threadsafe..**.
32230 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
32240 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
32250 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
32260 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
32270 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  .  ^For.** examp
32280 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
32290 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
322a0 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
322b0 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
322c0 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
322d0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
322e0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
322f0 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
32300 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
32310 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
32320 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
32330 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
32340 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
32350 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
32360 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
32370 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
32380 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
32390 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
323a0 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
323b0 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
323c0 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
323d0 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
323e0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
323f0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
32400 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
32410 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
32420 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
32430 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
32440 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
32450 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
32460 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
32470 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
32480 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
32490 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
324a0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
324b0 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
324c0 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
324d0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
324e0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
324f0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
32500 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
32510 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
32520 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
32530 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
32540 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
32550 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
32560 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
32570 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
32580 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
32590 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
325a0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
325b0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
325c0 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
325d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
325e0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
325f0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
32600 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
32610 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
32620 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
32630 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
32640 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a  [CAST] to BLOB.*
32650 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
32660 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
32670 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
32680 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
32690 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
326a0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
326b0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
326c0 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  L.** <tr><td>  T
326d0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
326e0 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
326f0 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
32700 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
32710 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
32720 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
32730 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
32740 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
32750 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
32760 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
32770 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
32780 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
32790 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
327a0 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
327b0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
327c0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
327d0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
327e0 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
327f0 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
32800 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
32810 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
32820 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
32830 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
32840 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
32850 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
32860 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
32870 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
32880 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
32890 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
328a0 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
328b0 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
328c0 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
328d0 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
328e0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
328f0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
32900 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
32910 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
32920 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
32930 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
32940 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
32950 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
32960 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
32970 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
32980 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
32990 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
329a0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
329b0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
329c0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
329d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
329e0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
329f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32a00 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
32a10 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
32a20 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
32a30 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
32a40 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
32a50 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
32a60 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
32a70 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
32a80 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
32a90 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
32aa0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
32ab0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
32ac0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
32ad0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
32ae0 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
32af0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
32b00 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
32b10 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
32b20 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
32b30 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
32b40 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
32b50 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
32b60 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
32b70 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
32b80 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
32b90 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
32ba0 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
32bb0 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
32bc0 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
32bd0 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
32be0 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
32bf0 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
32c00 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
32c10 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
32c20 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
32c30 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
32c40 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
32c50 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
32c60 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
32c70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
32c80 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20  afest policy is 
32c90 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
32ca0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
32cb0 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
32cc0 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
32cd0 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
32ce0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
32cf0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
32d00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32d10 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
32d20 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
32d30 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
32d40 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
32d50 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
32d60 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
32d70 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
32d80 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
32d90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32da0 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
32db0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
32dc0 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
32dd0 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
32de0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
32df0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
32e00 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
32e10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32e20 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
32e30 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
32e40 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
32e50 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
32e60 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
32e70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
32e80 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
32e90 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
32ea0 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
32eb0 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
32ec0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
32ed0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
32ee0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
32ef0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
32f00 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
32f10 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
32f20 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
32f30 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
32f40 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
32f50 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
32f60 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
32f70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32f80 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
32f90 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
32fa0 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
32fb0 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
32fc0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
32fd0 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
32fe0 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
32ff0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
33000 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
33010 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
33020 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
33030 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
33040 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
33050 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
33060 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
33070 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
33080 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e  ically.  Do <em>
33090 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68  not</em> pass th
330a0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
330b0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
330c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
330d0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
330e0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
330f0 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
33100 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
33110 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
33120 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
33130 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
33140 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
33150 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
33160 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
33170 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
33180 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
33190 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
331a0 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
331b0 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
331c0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
331d0 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
331e0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
331f0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
33200 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
33210 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
33220 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
33230 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20  EM].)^.*/.const 
33240 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
33250 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
33260 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
33270 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
33280 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
33290 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
332a0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
332b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
332c0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
332d0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
332e0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
332f0 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
33300 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
33310 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
33320 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
33330 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
33340 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
33350 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
33360 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
33370 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
33380 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
33390 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
333a0 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
333b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
333c0 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
333d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
333e0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
333f0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
33400 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
33410 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
33420 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
33430 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
33440 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
33450 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
33460 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
33470 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33480 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
33490 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
334a0 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54  ject.** DESTRUCT
334b0 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OR: sqlite3_stmt
334c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
334d0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
334e0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
334f0 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
33500 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33510 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
33520 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
33530 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
33540 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
33550 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  ed no errors.** 
33560 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  or if the statem
33570 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65  ent is never bee
33580 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65  n evaluated, the
33590 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  n sqlite3_finali
335a0 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ze() returns.** 
335b0 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20  SQLITE_OK.  ^If 
335c0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
335d0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74  evaluation of st
335e0 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64  atement S failed
335f0 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
33600 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65  3_finalize(S) re
33610 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70  turns the approp
33620 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
33630 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
33640 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
33650 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33660 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
33670 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
33680 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
33690 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20  t during.** the 
336a0 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70  life cycle of [p
336b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
336c0 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20  t] S:.** before 
336d0 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65  statement S is e
336e0 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61  ver evaluated, a
336f0 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  fter.** one or m
33700 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ore calls to [sq
33710 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20  lite3_reset()], 
33720 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c  or after any cal
33730 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  l.** to [sqlite3
33740 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c  _step()] regardl
33750 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
33760 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d  r not the statem
33770 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c  ent has.** compl
33780 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a  eted execution..
33790 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20  **.** ^Invoking 
337a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
337b0 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  () on a NULL poi
337c0 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65  nter is a harmle
337d0 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
337e0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
337f0 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76  must finalize ev
33800 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74  ery [prepared st
33810 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65  atement] in orde
33820 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65  r to avoid.** re
33830 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49  source leaks.  I
33840 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20  t is a grievous 
33850 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70  error for the ap
33860 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79  plication to try
33870 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65   to use.** a pre
33880 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
33890 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
338a0 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e  n finalized.  An
338b0 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61  y use of a prepa
338c0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
338d0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
338e0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e  en finalized can
338f0 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
33900 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65  ined and.** unde
33910 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
33920 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c   such as segfaul
33930 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72  ts and heap corr
33940 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  uption..*/.int s
33950 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
33960 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
33970 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
33980 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
33990 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
339a0 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48  t Object.** METH
339b0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
339c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
339d0 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
339e0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
339f0 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
33a00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
33a10 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20   object back to 
33a20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
33a30 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
33a40 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e  e-executed..** ^
33a50 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
33a60 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
33a70 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
33a80 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
33a90 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
33aa0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
33ab0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
33ac0 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
33ad0 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
33ae0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
33af0 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
33b00 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
33b10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
33b20 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
33b30 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
33b40 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
33b50 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63  tement] S.** bac
33b60 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
33b70 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
33b80 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  m..**.** ^If the
33b90 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
33ba0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
33bb0 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
33bc0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
33bd0 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
33be0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
33bf0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
33c00 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74  .** or if [sqlit
33c10 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
33c20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
33c30 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
33c40 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * then [sqlite3_
33c50 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
33c60 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
33c70 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
33c80 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
33c90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
33ca0 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
33cb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33cc0 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
33cd0 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
33ce0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
33cf0 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
33d00 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
33d10 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
33d20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
33d30 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
33d40 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
33d50 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f   the values.** o
33d60 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
33d70 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
33d80 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
33d90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
33da0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
33db0 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
33dc0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
33dd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
33de0 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
33df0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
33e00 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
33e10 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
33e20 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
33e30 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
33e40 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
33e50 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
33e60 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
33e70 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
33e80 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54  unctions}.** MET
33e90 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
33ea0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
33eb0 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
33ec0 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63  y known as "func
33ed0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
33ee0 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20  utines").** are 
33ef0 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
33f00 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
33f10 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65  regates or to re
33f20 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
33f30 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69  ior.** of existi
33f40 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
33f50 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
33f60 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
33f70 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a  ences between.**
33f80 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
33f90 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63  are the text enc
33fa0 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66  oding expected f
33fb0 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  or.** the second
33fc0 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
33fd0 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63  name of the func
33fe0 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74  tion being creat
33ff0 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70  ed).** and the p
34000 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e  resence or absen
34010 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74  ce of a destruct
34020 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a  or callback for.
34030 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
34040 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
34050 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
34060 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
34070 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
34080 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
34090 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
340a0 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
340b0 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
340c0 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
340d0 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
340e0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
340f0 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
34100 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
34110 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
34120 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
34130 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
34140 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
34150 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
34160 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
34170 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
34180 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
34190 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
341a0 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
341b0 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
341c0 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
341d0 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20  ed to 255 bytes 
341e0 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65  in a UTF-8.** re
341f0 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78  presentation, ex
34200 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
34210 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
34220 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
34230 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c  name.** length l
34240 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38  imit is in UTF-8
34250 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72   bytes, not char
34260 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31  acters nor UTF-1
34270 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41  6 bytes.  .** ^A
34280 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
34290 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
342a0 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
342b0 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
342c0 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  t in [SQLITE_MIS
342d0 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72  USE] being retur
342e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
342f0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
34300 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65  (nArg).** is the
34310 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
34320 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
34330 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
34340 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
34350 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d  . ^If this param
34360 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
34370 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
34380 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
34390 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
343a0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
343b0 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
343c0 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
343d0 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
343e0 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
343f0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
34400 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
34410 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
34420 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
34430 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
34440 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
34450 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
34460 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
34470 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
34480 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
34490 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
344a0 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
344b0 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
344c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
344d0 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
344e0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68   parameters.  Th
344f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
34500 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61  ould set this pa
34510 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53  rameter to.** [S
34520 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69  QLITE_UTF16LE] i
34530 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
34540 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
34550 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74  vokes .** [sqlit
34560 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
34570 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
34580 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
34590 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20  16BE] if the.** 
345a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
345b0 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f  nvokes [sqlite3_
345c0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
345d0 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
345e0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  r.** [SQLITE_UTF
345f0 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  16] if [sqlite3_
34600 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
34610 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c  is used, or [SQL
34620 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68  ITE_UTF8].** oth
34630 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61  erwise.  ^The sa
34640 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
34650 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
34660 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
34670 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72   using.** differ
34680 65 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65  ent preferred te
34690 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69  xt encodings, wi
346a0 74 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70  th different imp
346b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
346c0 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e  .** each encodin
346d0 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  g..** ^When mult
346e0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
346f0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
34700 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
34710 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
34720 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
34730 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
34740 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
34750 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
34760 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ersion..**.** ^T
34770 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
34780 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c  ter may optional
34790 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20  ly be ORed with 
347a0 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
347b0 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67  ISTIC].** to sig
347c0 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e  nal that the fun
347d0 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79  ction will alway
347e0 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  s return the sam
347f0 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a  e result given.*
34800 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  * the same input
34810 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c  s within a singl
34820 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
34830 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74    Most SQL funct
34840 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65  ions are.** dete
34850 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
34860 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d  built-in [random
34870 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ()] SQL function
34880 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   is an example o
34890 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  f a.** function 
348a0 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65  that is not dete
348b0 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
348c0 53 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61  SQLite query pla
348d0 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a  nner is able to.
348e0 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74  ** perform addit
348f0 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69  ional optimizati
34900 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69  ons on determini
34910 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20  stic functions, 
34920 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65  so use.** of the
34930 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49   [SQLITE_DETERMI
34940 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20  NISTIC] flag is 
34950 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72  recommended wher
34960 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a  e possible..**.*
34970 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
34980 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
34990 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
349a0 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
349b0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
349c0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
349d0 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
349e0 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
349f0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
34a00 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
34a10 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68  e sixth, seventh
34a20 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61   and eighth para
34a30 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
34a40 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
34a50 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
34a60 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
34a70 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
34a80 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
34a90 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
34aa0 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61  ggregate. ^A sca
34ab0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
34ac0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
34ad0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
34ae0 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
34af0 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20  back only; NULL 
34b00 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65  pointers must be
34b10 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
34b20 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
34b30 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
34b40 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
34b50 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
34b60 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
34b70 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
34b80 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
34b90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73  NULL pointer mus
34ba0 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  t be passed for 
34bb0 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74  xFunc. ^To delet
34bc0 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a  e an existing.**
34bd0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
34be0 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
34bf0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66   NULL pointers f
34c00 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
34c10 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ction.** callbac
34c20 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ks..**.** ^(If t
34c30 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  he ninth paramet
34c40 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
34c50 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
34c60 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a  () is not NULL,.
34c70 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65  ** then it is de
34c80 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
34c90 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
34ca0 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54  a pointer. .** T
34cb0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
34cc0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
34cd0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  e function is de
34ce0 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79  leted, either by
34cf0 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f   being.** overlo
34d00 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65  aded or when the
34d10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
34d20 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a  tion closes.)^.*
34d30 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f  * ^The destructo
34d40 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65  r is also invoke
34d50 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  d if the call to
34d60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
34d70 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
34d80 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e   fails..** ^When
34d90 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
34da0 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
34db0 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  tenth parameter 
34dc0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a  is invoked, it.*
34dd0 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69  * is passed a si
34de0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
34df0 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ich is a copy of
34e00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34e10 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65   data .** pointe
34e20 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
34e30 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
34e40 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
34e50 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e  e_function_v2().
34e60 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65  .**.** ^It is pe
34e70 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
34e80 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
34e90 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
34ea0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
34eb0 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
34ec0 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
34ed0 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
34ee0 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
34ef0 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
34f00 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
34f10 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
34f20 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
34f30 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
34f40 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d  mentation that m
34f50 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
34f60 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
34f70 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
34f80 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
34f90 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69  .  ^A function i
34fa0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
34fb0 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
34fc0 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
34fd0 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
34fe0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
34ff0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
35000 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
35010 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e  egative nArg.  ^
35020 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
35030 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
35040 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
35050 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61  matches the data
35060 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
35070 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74   a better.** mat
35080 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
35090 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
350a0 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
350b0 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63  nt.  .** ^A func
350c0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
350d0 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
350e0 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
350f0 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
35100 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
35110 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
35120 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
35130 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
35140 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
35150 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
35160 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d  6..**.** ^Built-
35170 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
35180 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
35190 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
351a0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
351b0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ons..**.** ^An a
351c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
351d0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
351e0 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
351f0 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
35200 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
35210 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c  wever, such call
35220 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c  s must not.** cl
35230 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
35240 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20   connection nor 
35250 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65  finalize or rese
35260 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  t the prepared.*
35270 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77  * statement in w
35280 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f  hich the functio
35290 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
352a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
352b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
352c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
352d0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
352e0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
352f0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
35300 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
35310 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
35320 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
35330 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
35340 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
35350 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
35360 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
35370 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
35380 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
35390 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
353a0 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
353b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
353c0 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
353d0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f   *db,.  const vo
353e0 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  id *zFunctionNam
353f0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
35400 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
35410 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
35420 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
35430 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
35440 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
35450 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
35460 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
35470 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
35480 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
35490 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
354a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
354b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
354c0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
354d0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
354e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
354f0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
35500 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
35510 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
35520 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
35530 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
35540 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
35550 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
35560 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
35570 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
35580 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
35590 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
355a0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
355b0 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28  ntext*),.  void(
355c0 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
355d0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
355e0 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
355f0 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ings.**.** These
35600 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
35610 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
35620 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
35630 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
35640 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
35650 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
35660 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
35670 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
35680 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    1    /* IMP: R
35690 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a  -37514-35566 */.
356a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
356b0 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 20  TF16LE        2 
356c0 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33     /* IMP: R-033
356d0 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66  71-37637 */.#def
356e0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
356f0 42 45 20 20 20 20 20 20 20 20 33 20 20 20 20 2f  BE        3    /
35700 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33  * IMP: R-51971-3
35710 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20  4154 */.#define 
35720 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
35730 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
35740 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
35750 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
35760 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
35770 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70       5    /* Dep
35780 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69  recated */.#defi
35790 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
357a0 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
357b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
357c0 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
357d0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
357e0 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67  F: Function Flag
357f0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
35800 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f  nstants may be O
35810 52 65 64 20 74 6f 67 65 74 68 65 72 20 77 69 74  Red together wit
35820 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
35830 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72 72  E_UTF8 | preferr
35840 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
35850 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  ] as the fourth 
35860 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b  argument.** to [
35870 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
35880 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c  unction()], [sql
35890 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
358a0 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
358b0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
358c0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e  _function_v2()].
358d0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
358e0 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
358f0 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a      0x800../*.**
35900 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65   CAPI3REF: Depre
35910 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a  cated Functions.
35920 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a  ** DEPRECATED.**
35930 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
35940 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61  ons are [depreca
35950 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20  ted].  In order 
35960 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
35970 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
35980 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
35990 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75  r code, these fu
359a0 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  nctions continue
359b0 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f   .** to be suppo
359c0 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20  rted.  However, 
359d0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
359e0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a   should avoid.**
359f0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73   the use of thes
35a00 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f  e functions.  To
35a10 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 72   encourage progr
35a20 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 0a  ammers to avoid.
35a30 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ** these functio
35a40 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20  ns, we will not 
35a50 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74 68 65  explain what the
35a60 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  y do..*/.#ifndef
35a70 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50   SQLITE_OMIT_DEP
35a80 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44  RECATED.SQLITE_D
35a90 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
35aa0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
35ab0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
35ac0 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
35ad0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
35ae0 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
35af0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
35b00 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
35b10 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
35b20 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
35b30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
35b40 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
35b50 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
35b60 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
35b70 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
35b80 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
35b90 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
35ba0 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
35bb0 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
35bc0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
35bd0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
35be0 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
35bf0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
35c00 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  t),.            
35c10 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c            void*,
35c20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
35c30 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
35c40 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
35c50 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20  g SQL Values.** 
35c60 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
35c70 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  value.**.** The 
35c80 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
35c90 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
35ca0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
35cb0 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
35cc0 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
35cd0 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
35ce0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
35cf0 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
35d00 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
35d10 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
35d20 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75    .**.** The xFu
35d30 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
35d40 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
35d50 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
35d60 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
35d70 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
35d80 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
35d90 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
35da0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
35db0 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
35dc0 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
35dd0 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
35de0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
35df0 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33  egates..** The 3
35e00 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
35e10 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
35e20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
35e30 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
35e40 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
35e50 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
35e60 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
35e70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
35e80 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
35e90 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
35ea0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
35eb0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
35ec0 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
35ed0 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
35ee0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
35ef0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
35f00 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
35f10 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
35f20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
35f30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
35f40 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
35f50 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
35f60 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
35f70 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
35f80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
35f90 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
35fa0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
35fb0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
35fc0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
35fd0 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
35fe0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
35ff0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
36000 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
36010 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72 6f  pt that these ro
36020 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
36030 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
36040 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
36050 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
36060 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
36070 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
36080 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
36090 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
360a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
360b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
360c0 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
360d0 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
360e0 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
360f0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
36100 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
36110 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
36120 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
36130 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
36140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
36150 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
36160 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
36170 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
36180 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
36190 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
361a0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
361b0 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
361c0 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
361d0 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
361e0 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
361f0 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
36200 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
36210 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
36220 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
36230 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
36240 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
36250 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
36260 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
36270 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
36280 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
36290 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
362a0 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
362b0 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
362c0 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
362d0 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
362e0 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
362f0 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
36300 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
36310 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
36320 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
36330 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
36340 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
36350 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
36360 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
36370 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
36380 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
36390 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
363a0 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
363b0 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
363c0 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
363d0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
363e0 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
363f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
36400 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
36410 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
36420 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
36430 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
36440 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
36450 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
36460 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
36470 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
36480 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
36490 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
364a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
364b0 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
364c0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
364d0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
364e0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
364f0 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
36500 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
36510 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
36520 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
36530 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
36540 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
36550 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
36560 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
36570 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
36580 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
36590 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
365a0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
365b0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
365c0 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
365d0 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
365e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
365f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
36600 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
36610 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
36620 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
36630 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
36640 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
36650 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
36660 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
36670 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
36680 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
36690 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
366a0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
366b0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
366c0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
366d0 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
366e0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
366f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
36700 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
36710 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
36720 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
36730 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
36740 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
36750 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
36760 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
36770 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
36780 49 33 52 45 46 3a 20 46 69 6e 64 69 6e 67 20 54  I3REF: Finding T
36790 68 65 20 53 75 62 74 79 70 65 20 4f 66 20 53 51  he Subtype Of SQ
367a0 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48  L Values.** METH
367b0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  OD: sqlite3_valu
367c0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
367d0 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70  te3_value_subtyp
367e0 65 28 56 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  e(V) function re
367f0 74 75 72 6e 73 20 74 68 65 20 73 75 62 74 79 70  turns the subtyp
36800 65 20 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70 70  e for.** an [app
36810 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36820 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 61   SQL function] a
36830 72 67 75 6d 65 6e 74 20 56 2e 20 20 54 68 65 20  rgument V.  The 
36840 73 75 62 74 79 70 65 0a 2a 2a 20 69 6e 66 6f 72  subtype.** infor
36850 6d 61 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  mation can be us
36860 65 64 20 74 6f 20 70 61 73 73 20 61 20 6c 69 6d  ed to pass a lim
36870 69 74 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 63  ited amount of c
36880 6f 6e 74 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f  ontext from.** o
36890 6e 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ne SQL function 
368a0 74 6f 20 61 6e 6f 74 68 65 72 2e 20 20 55 73 65  to another.  Use
368b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
368c0 73 75 6c 74 5f 73 75 62 74 79 70 65 28 29 5d 0a  sult_subtype()].
368d0 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 73 65  ** routine to se
368e0 74 20 74 68 65 20 73 75 62 74 79 70 65 20 66 6f  t the subtype fo
368f0 72 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  r the return val
36900 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 66 75 6e  ue of an SQL fun
36910 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ction..**.** SQL
36920 69 74 65 20 6d 61 6b 65 73 20 6e 6f 20 75 73 65  ite makes no use
36930 20 6f 66 20 73 75 62 74 79 70 65 20 69 74 73 65   of subtype itse
36940 6c 66 2e 20 20 49 74 20 6d 65 72 65 6c 79 20 70  lf.  It merely p
36950 61 73 73 65 73 20 74 68 65 20 73 75 62 74 79 70  asses the subtyp
36960 65 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 72 65  e.** from the re
36970 73 75 6c 74 20 6f 66 20 6f 6e 65 20 5b 61 70 70  sult of one [app
36980 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36990 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 69   SQL function] i
369a0 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74  nto the.** input
369b0 20 6f 66 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a   of another..*/.
369c0 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 71 6c  unsigned int sql
369d0 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79  ite3_value_subty
369e0 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
369f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
36a00 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 20 46 72  REF: Copy And Fr
36a10 65 65 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a  ee SQL Values.**
36a20 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
36a30 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  _value.**.** ^Th
36a40 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
36a50 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65  dup(V) interface
36a60 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
36a70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
36a80 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 44  lue].** object D
36a90 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
36aa0 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 63  ointer to that c
36ab0 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  opy.  ^The [sqli
36ac0 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 74 75 72  te3_value] retur
36ad0 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70 72 6f  ned.** is a [pro
36ae0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
36af0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65 76 65  alue] object eve
36b00 6e 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 69  n if the input i
36b10 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  s not..** ^The s
36b20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
36b30 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (V) interface re
36b40 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 56 20  turns NULL if V 
36b50 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20 61 0a  is NULL or if a.
36b60 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
36b70 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  tion fails..**.*
36b80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
36b90 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 6e 74  alue_free(V) int
36ba0 65 72 66 61 63 65 20 66 72 65 65 73 20 61 6e 20  erface frees an 
36bb0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
36bc0 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76 69 6f  object.** previo
36bd0 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
36be0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
36bf0 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66 20 56  e_dup()].  ^If V
36c00 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
36c10 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  er.** then sqlit
36c20 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29  e3_value_free(V)
36c30 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
36c40 6f 2d 6f 70 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  o-op..*/.sqlite3
36c50 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
36c60 76 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 20  value_dup(const 
36c70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
36c80 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 76 61  .void sqlite3_va
36c90 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33  lue_free(sqlite3
36ca0 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
36cb0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
36cc0 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
36cd0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20  tion Context.** 
36ce0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
36cf0 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  context.**.** Im
36d00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
36d10 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
36d20 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
36d30 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  s.** routine to 
36d40 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
36d50 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
36d60 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  r state..**.** ^
36d70 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
36d80 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
36d90 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
36da0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
36db0 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61  led .** for a pa
36dc0 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
36dd0 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c  te function, SQL
36de0 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73  ite.** allocates
36df0 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65   N of memory, ze
36e00 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65  roes out that me
36e10 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
36e20 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
36e30 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79  o the new memory
36e40 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  . ^On second and
36e50 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
36e60 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
36e70 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
36e80 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
36e90 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
36ea0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a  ion instance,.**
36eb0 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
36ec0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53   is returned.  S
36ed0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
36ee0 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f  _context() is no
36ef0 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  rmally.** called
36f00 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69   once for each i
36f10 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
36f20 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20   xStep callback 
36f30 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20  and then one.** 
36f40 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74  last time when t
36f50 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
36f60 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
36f70 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d  ^(When no rows m
36f80 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65  atch.** an aggre
36f90 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
36fa0 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b  xStep() callback
36fb0 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
36fc0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d  e function.** im
36fd0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
36fe0 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64  never called and
36ff0 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c   xFinal() is cal
37000 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  led exactly once
37010 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61  ..** In those ca
37020 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67  ses, sqlite3_agg
37030 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
37040 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
37050 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73   for the.** firs
37060 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68  t time from with
37070 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a  in xFinal().)^.*
37080 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37090 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
370a0 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
370b0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
370c0 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e  pointer .** when
370d0 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66   first called if
370e0 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
370f0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
37100 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a   or if a memory.
37110 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f  ** allocate erro
37120 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
37130 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  ^(The amount of 
37140 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20  space allocated 
37150 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  by sqlite3_aggre
37160 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
37170 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ) is.** determin
37180 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61  ed by the N para
37190 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73  meter on first s
371a0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20  uccessful call. 
371b0 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a   Changing the.**
371c0 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73   value of N in s
371d0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
371e0 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
371f0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69  ate_context() wi
37200 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  thin.** the same
37210 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
37220 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c  ion instance wil
37230 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65  l not resize the
37240 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
37250 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e  ation.)^  Within
37260 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
37270 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74  back, it is cust
37280 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20  omary to set.** 
37290 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20  N=0 in calls to 
372a0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
372b0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73  e_context(C,N) s
372c0 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f  o that no .** po
372d0 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61  intless memory a
372e0 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72  llocations occur
372f0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
37300 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
37310 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
37320 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
37330 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
37340 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
37350 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
37360 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
37370 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
37380 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
37390 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
373a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
373b0 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
373c0 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
373d0 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
373e0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
373f0 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
37400 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
37410 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
37420 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
37430 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
37440 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
37450 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
37460 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
37470 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
37480 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
37490 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
374a0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
374b0 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
374c0 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
374d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
374e0 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
374f0 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
37500 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
37510 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
37520 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
37530 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37540 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
37550 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
37560 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
37570 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
37580 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
37590 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
375a0 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
375b0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
375c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
375d0 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
375e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
375f0 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
37600 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
37610 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
37620 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
37630 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
37640 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
37650 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
37660 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
37670 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
37680 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
37690 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
376a0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
376b0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
376c0 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
376d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
376e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
376f0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
37700 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
37710 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
37720 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a  ite3_context.**.
37730 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37740 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
37750 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
37760 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
37770 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
37780 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
37790 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65  connection] (the
377a0 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a   1st parameter).
377b0 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
377c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
377d0 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
377e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
377f0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
37800 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
37810 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
37820 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
37830 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
37840 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  on..*/.sqlite3 *
37850 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
37860 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
37870 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
37880 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
37890 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
378a0 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Data.** METHOD:
378b0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
378c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
378d0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
378e0 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65  ed by (non-aggre
378f0 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69  gate) SQL functi
37900 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
37910 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
37920 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
37930 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
37940 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
37950 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
37960 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
37970 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
37980 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
37990 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
379a0 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
379b0 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
379c0 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
379d0 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
379e0 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20    An example.** 
379f0 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d 69  of where this mi
37a00 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 73  ght be useful is
37a10 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78   in a regular-ex
37a20 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
37a30 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  g.** function. T
37a40 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
37a50 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
37a60 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
37a70 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a  n be stored as.*
37a80 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
37a90 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70  iated with the p
37aa0 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20  attern string.  
37ab0 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67  .** Then as long
37ac0 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e 20   as the pattern 
37ad0 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74  string remains t
37ae0 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20  he same,.** the 
37af0 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
37b00 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
37b10 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
37b20 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
37b30 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
37b40 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
37b50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
37b60 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
37b70 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
37b80 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
37b90 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
37ba0 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
37bb0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
37bc0 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
37bd0 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
37be0 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
37bf0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
37c00 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
37c10 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ^If there is no 
37c20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
37c30 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
37c40 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
37c50 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f  t, this sqlite3_
37c60 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
37c70 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
37c80 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
37c90 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
37ca0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
37cb0 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72  a(C,N,P,X) inter
37cc0 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73 20  face saves P as 
37cd0 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
37ce0 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
37cf0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
37d00 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
37d10 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75  ction.  ^Subsequ
37d20 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
37d30 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
37d40 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20  ata(C,N) return 
37d50 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20  P from the most 
37d60 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65  recent.** sqlite
37d70 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
37d80 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74  N,P,X) call if t
37d90 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 73  he metadata is s
37da0 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a  till valid or.**
37db0 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74   NULL if the met
37dc0 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 64  adata has been d
37dd0 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66  iscarded..** ^Af
37de0 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f  ter each call to
37df0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
37e00 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68  data(C,N,P,X) wh
37e10 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c  ere X is not NUL
37e20 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  L,.** SQLite wil
37e30 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
37e40 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
37e50 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 65   X with paramete
37e60 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f  r P exactly.** o
37e70 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65  nce, when the me
37e80 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61 72  tadata is discar
37e90 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ded..** SQLite i
37ea0 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72  s free to discar
37eb0 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 61  d the metadata a
37ec0 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c  t any time, incl
37ed0 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c  uding: <ul>.** <
37ee0 6c 69 3e 20 5e 28 77 68 65 6e 20 74 68 65 20 63  li> ^(when the c
37ef0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
37f00 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
37f10 63 68 61 6e 67 65 73 29 5e 2c 20 6f 72 0a 2a 2a  changes)^, or.**
37f20 20 3c 6c 69 3e 20 5e 28 77 68 65 6e 20 5b 73 71   <li> ^(when [sq
37f30 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
37f40 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
37f50 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
37f60 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
37f70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 29 5e   SQL statement)^
37f80 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5e 28 77  , or.** <li> ^(w
37f90 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  hen sqlite3_set_
37fa0 61 75 78 64 61 74 61 28 29 20 69 73 20 69 6e 76  auxdata() is inv
37fb0 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  oked again on th
37fc0 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
37fd0 70 61 72 61 6d 65 74 65 72 29 5e 2c 20 6f 72 0a  parameter)^, or.
37fe0 2a 2a 20 3c 6c 69 3e 20 5e 28 64 75 72 69 6e 67  ** <li> ^(during
37ff0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71   the original sq
38000 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
38010 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20  a() call when a 
38020 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20  memory .**      
38030 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
38040 20 6f 63 63 75 72 73 2e 29 5e 20 3c 2f 75 6c 3e   occurs.)^ </ul>
38050 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20  .**.** Note the 
38060 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70  last bullet in p
38070 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20  articular.  The 
38080 64 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20  destructor X in 
38090 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
380a0 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
380b0 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
380c0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
380d0 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69  fore the.** sqli
380e0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
380f0 29 20 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e  ) interface even
38100 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65   returns.  Hence
38110 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
38120 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64  data().** should
38130 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20   be called near 
38140 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
38150 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
38160 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a  tation and the.*
38170 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  * function imple
38180 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
38190 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73   not make any us
381a0 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20  e of P after.** 
381b0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
381c0 61 74 61 28 29 20 68 61 73 20 62 65 65 6e 20 63  ata() has been c
381d0 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  alled..**.** ^(I
381e0 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
381f0 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
38200 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
38210 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
38220 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
38230 65 72 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d  ers that are com
38240 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61  pile-time consta
38250 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c  nts, including l
38260 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
38270 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
38280 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e  ] and expression
38290 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20  s composed from 
382a0 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a  the same.)^.**.*
382b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
382c0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
382d0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
382e0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
382f0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
38300 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
38310 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67  .void *sqlite3_g
38320 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
38330 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
38340 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65   N);.void sqlite
38350 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
38360 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
38370 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
38380 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
38390 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
383a0 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
383b0 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
383c0 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
383d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
383e0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20   special values 
383f0 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
38400 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
38410 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
38420 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
38430 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
38440 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
38450 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  lob()].  ^If the
38460 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
38470 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
38480 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
38490 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
384a0 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
384b0 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
384c0 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
384d0 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
384e0 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
384f0 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51  yed.  ^The.** SQ
38500 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
38510 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
38520 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
38530 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
38540 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
38550 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
38560 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
38570 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
38580 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
38590 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
385a0 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
385b0 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
385c0 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
385d0 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
385e0 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
385f0 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f  ++ compilers..*/
38600 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
38610 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
38620 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
38630 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38640 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
38650 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
38660 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
38670 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
38680 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
38690 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
386a0 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
386b0 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
386c0 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
386d0 46 75 6e 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54 48  Function.** METH
386e0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
386f0 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ext.**.** These 
38700 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
38710 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
38720 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
38730 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
38740 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
38750 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
38760 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
38770 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
38780 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
38790 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
387a0 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
387b0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
387c0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
387d0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
387e0 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
387f0 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  e the [parameter
38800 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79   binding] family
38810 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   of.** functions
38820 20 75 73 65 6