/ Hex Artifact Content
Login

Artifact 4a030e254e204570444b34bf7d40fb4a5416089e:


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 0a 2f 2a 20 64 65 70 72 65      28../* depre
c3c0: 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23  cated names */.#
c3d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45  define SQLITE_GE
c3e0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
c3f0: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
c400: 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_GET_LOCKPROXYF
c410: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  ILE.#define SQLI
c420: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
c430: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
c440: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50  _FCNTL_SET_LOCKP
c450: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
c460: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
c470: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53  NO             S
c480: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54  QLITE_FCNTL_LAST
c490: 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  _ERRNO.../*.** C
c4a0: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
c4b0: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  andle.**.** The 
c4c0: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74  mutex module wit
c4d0: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e  hin SQLite defin
c4e0: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  es [sqlite3_mute
c4f0: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61  x] to be an.** a
c500: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72  bstract type for
c510: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e   a mutex object.
c520: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
c530: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a  e never looks.**
c540: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   at the internal
c550: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
c560: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d  of an [sqlite3_m
c570: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a  utex].  It only.
c580: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f  ** deals with po
c590: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73  inters to the [s
c5a0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62  qlite3_mutex] ob
c5b0: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65  ject..**.** Mute
c5c0: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20  xes are created 
c5d0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
c5e0: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  utex_alloc()]..*
c5f0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
c600: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73   sqlite3_mutex s
c610: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f  qlite3_mutex;../
c620: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
c630: 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69 6f  oadable Extensio
c640: 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20  n Thunk.**.** A 
c650: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6f  pointer to the o
c660: 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61 70  paque sqlite3_ap
c670: 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75 63  i_routines struc
c680: 74 75 72 65 20 69 73 20 70 61 73 73 65 64 20 61  ture is passed a
c690: 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70  s.** the third p
c6a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74 72  arameter to entr
c6b0: 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61  y points of [loa
c6c0: 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73  dable extensions
c6d0: 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72 75  ].  This.** stru
c6e0: 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 74 79  cture must be ty
c6f0: 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65 72  pedefed in order
c700: 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
c710: 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67  compiler warning
c720: 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61  s.** on some pla
c730: 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64  tforms..*/.typed
c740: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
c750: 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73  3_api_routines s
c760: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
c770: 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nes;../*.** CAPI
c780: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
c790: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ce Object.**.** 
c7a0: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
c7b0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
c7c0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
c7d0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
c7e0: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
c7f0: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
c800: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
c810: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
c820: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
c830: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
c840: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
c850: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
c860: 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68  tem".  See.** th
c870: 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63  e [VFS | VFS doc
c880: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
c890: 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74  further informat
c8a0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76  ion..**.** The v
c8b0: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72  alue of the iVer
c8c0: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
c8d0: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
c8e0: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a  y be larger in.*
c8f0: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * future version
c900: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64  s of SQLite.  Ad
c910: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
c920: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
c930: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  to this.** objec
c940: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73  t when the iVers
c950: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63  ion value is inc
c960: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68  reased.  Note th
c970: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
c980: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
c990: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
c9a0: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
c9b0: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  nsaction between
c9c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
c9d0: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36  on 3.5.9 and 3.6
c9e0: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  .0 and yet the i
c9f0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
ca00: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65  s not.** modifie
ca10: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
ca20: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
ca30: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
ca40: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
ca50: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
ca60: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
ca70: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
ca80: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
ca90: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
caa0: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
cab0: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
cac0: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
cad0: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
cae0: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
caf0: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
cb00: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
cb10: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
cb20: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
cb30: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
cb40: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
cb50: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
cb60: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
cb70: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
cb80: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
cb90: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
cba0: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
cbb0: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
cbc0: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
cbd0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
cbe0: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
cbf0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
cc00: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
cc10: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
cc20: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
cc30: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
cc40: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
cc50: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
cc60: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
cc70: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
cc80: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
cc90: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
cca0: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
ccb0: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
ccc0: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
ccd0: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
cce0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
ccf0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
cd00: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
cd10: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
cd20: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
cd30: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
cd40: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
cd50: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
cd60: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
cd70: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
cd80: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
cd90: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
cda0: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
cdb0: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
cdc0: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
cdd0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a  3_vfs.xOpen]].**
cde0: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
cdf0: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69  ees that the zFi
ce00: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
ce10: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20   to xOpen.** is 
ce20: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
ce30: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20  inter or string 
ce40: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
ce50: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
ce60: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61   with an optiona
ce70: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a  l suffix added..
ce80: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20  ** ^If a suffix 
ce90: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  is added to the 
cea0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
ceb0: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20  ter, it will.** 
cec0: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e  consist of a sin
ced0: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65  gle "-" characte
cee0: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f  r followed by no
cef0: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31   more than.** 11
cf00: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e   alphanumeric an
cf10: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74  d/or "-" charact
cf20: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ers..** ^SQLite 
cf30: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
cf40: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
cf50: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
cf60: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
cf70: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
cf80: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42   is.** called. B
cf90: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
cfa0: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
cfb0: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
cfc0: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
cfd0: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
cfe0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
cff0: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
d000: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
d010: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
d020: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
d030: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
d040: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
d050: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
d060: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
d070: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74  * must invent it
d080: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
d090: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
d0a0: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68  e.  ^Whenever th
d0b0: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
d0c0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
d0d0: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
d0e0: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
d0f0: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
d100: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
d110: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
d120: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
d130: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
d140: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
d150: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
d160: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
d170: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
d180: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
d190: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
d1a0: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
d1b0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
d1c0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
d1d0: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
d1e0: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
d1f0: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
d200: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
d210: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
d220: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70  ATE]. .** If xOp
d230: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
d240: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
d250: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
d260: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
d270: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
d280: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
d290: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
d2a0: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
d2b0: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77  **.** ^(SQLite w
d2c0: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
d2d0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
d2e0: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
d2f0: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
d300: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
d310: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
d320: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
d330: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
d340: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
d350: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d360: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
d370: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d380: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
d390: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
d3a0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
d3b0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
d3c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
d3d0: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
d3e0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d3f0: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
d400: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d410: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
d420: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
d430: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a  ITE_OPEN_WAL].**
d440: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
d450: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
d460: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
d470: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
d480: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
d490: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
d4a0: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
d4b0: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
d4c0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
d4d0: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
d4e0: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
d4f0: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
d500: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
d510: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
d520: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
d530: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
d540: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
d550: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
d560: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
d570: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
d580: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
d590: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
d5a0: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
d5b0: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
d5c0: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
d5d0: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
d5e0: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
d5f0: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
d600: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
d610: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
d620: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
d630: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
d640: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
d650: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
d660: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
d670: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
d680: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
d690: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
d6a0: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
d6b0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
d6c0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
d6d0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
d6e0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
d6f0: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
d700: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
d710: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d720: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
d730: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
d740: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
d750: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
d760: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  d.  ^The [SQLITE
d770: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
d780: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
d790: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74  set for TEMP dat
d7a0: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72  abases and their
d7b0: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73   journals, trans
d7c0: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65  ient.** database
d7d0: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61  s, and subjourna
d7e0: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ls..**.** ^The [
d7f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
d800: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
d810: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
d820: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
d830: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
d840: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
d850: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
d860: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
d870: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
d880: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
d890: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
d8a0: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
d8b0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
d8c0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
d8d0: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
d8e0: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
d8f0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
d900: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
d910: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
d920: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
d930: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
d940: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
d950: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
d960: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
d970: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
d980: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
d990: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
d9a0: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
d9b0: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
d9c0: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73  ..**.** ^At leas
d9d0: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
d9e0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
d9f0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
da00: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
da10: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
da20: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
da30: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
da40: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
da50: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e  Open.  The xOpen
da60: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
da70: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
da80: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
da90: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
daa0: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20  st fill it in.  
dab0: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  Note that.** the
dac0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75   xOpen method mu
dad0: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  st set the sqlit
dae0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
daf0: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20   to either.** a 
db00: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69  valid [sqlite3_i
db10: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
db20: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78  t or to NULL.  x
db30: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20  Open must do.** 
db40: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65  this even if the
db50: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51   open fails.  SQ
db60: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61  Lite expects tha
db70: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
db80: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65  le.pMethods.** e
db90: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76  lement will be v
dba0: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e  alid after xOpen
dbb0: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c   returns regardl
dbc0: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
dbd0: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65  ss.** or failure
dbe0: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61   of the xOpen ca
dbf0: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  ll..**.** [[sqli
dc00: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d  te3_vfs.xAccess]
dc10: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20  ].** ^The flags 
dc20: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
dc30: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
dc40: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
dc50: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
dc60: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
dc70: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
dc80: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
dc90: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
dca0: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
dcb0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
dcc0: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
dcd0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
dce0: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
dcf0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
dd00: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
dd10: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20  ble.   The file 
dd20: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65  can be a.** dire
dd30: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ctory..**.** ^SQ
dd40: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
dd50: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
dd60: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
dd70: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
dd80: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
dd90: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54  FullPathname.  T
dda0: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
ddb0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
ddc0: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
ddd0: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
dde0: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
ddf0: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74  hods. If the out
de00: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
de10: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
de20: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
de30: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
de40: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
de50: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
de60: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
de70: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
de80: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
de90: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
dea0: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
deb0: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
dec0: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
ded0: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
dee0: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
def0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
df00: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75  ), xSleep(), xCu
df10: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64  rrentTime(), and
df20: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
df30: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  64().** interfac
df40: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  es are not stric
df50: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
df60: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
df70: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
df80: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
df90: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
dfa0: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
dfb0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
dfc0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
dfd0: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
dfe0: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
dff0: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
e000: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
e010: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
e020: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
e030: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
e040: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
e050: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
e060: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
e070: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
e080: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
e090: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
e0a0: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
e0b0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
e0c0: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68  onds given.  ^Th
e0d0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
e0e0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
e0f0: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
e100: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
e110: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
e120: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f  time as.** a flo
e130: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
e140: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72  e..** ^The xCurr
e150: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
e160: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61  ethod returns, a
e170: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  s an integer, th
e180: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20  e Julian.** Day 
e190: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65  Number multiplie
e1a0: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
e1b0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
e1c0: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
e1d0: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
e1e0: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
e1f0: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
e200: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
e210: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
e220: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
e230: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
e240: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
e250: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
e260: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
e270: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
e280: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
e290: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
e2a0: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
e2b0: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
e2c0: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
e2d0: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
e2e0: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a  navailable..**.*
e2f0: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65  * ^The xSetSyste
e300: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73  mCall(), xGetSys
e310: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78  temCall(), and x
e320: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  NestSystemCall()
e330: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
e340: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74  re not used by t
e350: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he SQLite core. 
e360: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20   These optional 
e370: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
e380: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f  rovided.** by so
e390: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69  me VFSes to faci
e3a0: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f  litate testing o
e3b0: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20  f the VFS code. 
e3c0: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a  By overriding .*
e3d0: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77  * system calls w
e3e0: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e  ith functions un
e3f0: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c  der its control,
e400: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20   a test program 
e410: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20  can.** simulate 
e420: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72  faults and error
e430: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74   conditions that
e440: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
e450: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a   be difficult.**
e460: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74   or impossible t
e470: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73  o induce.  The s
e480: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c  et of system cal
e490: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  ls that can be o
e4a0: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72  verridden.** var
e4b0: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53  ies from one VFS
e4c0: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64   to another, and
e4d0: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f   from one versio
e4e0: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46  n of the same VF
e4f0: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74  S to the.** next
e500: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
e510: 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69  that use these i
e520: 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62  nterfaces must b
e530: 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61  e prepared for a
e540: 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20  ny.** or all of 
e550: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
e560: 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66   to be NULL or f
e570: 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f  or their behavio
e580: 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66  r to change.** f
e590: 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
e5a0: 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70  to the next.  Ap
e5b0: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
e5c0: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61  not attempt to a
e5d0: 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20  ccess.** any of 
e5e0: 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66  these methods if
e5f0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66   the iVersion of
e600: 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73   the VFS is less
e610: 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65   than 3..*/.type
e620: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
e630: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
e640: 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64  fs;.typedef void
e650: 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61   (*sqlite3_sysca
e660: 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73  ll_ptr)(void);.s
e670: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
e680: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
e690: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
e6a0: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
e6b0: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
e6c0: 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e  ently 3) */.  in
e6d0: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
e6e0: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
e6f0: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
e700: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
e710: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
e720: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
e730: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
e740: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
e750: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
e760: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
e770: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
e780: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
e790: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
e7a0: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
e7b0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
e7c0: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
e7d0: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
e7e0: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
e7f0: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
e800: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
e810: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
e820: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e830: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
e840: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
e850: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
e860: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
e870: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
e880: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
e890: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e8a0: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
e8b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
e8c0: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
e8d0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e8e0: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
e8f0: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
e900: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
e910: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
e920: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e930: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
e940: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
e950: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
e960: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e970: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
e980: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
e990: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
e9a0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
e9b0: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
e9c0: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
e9d0: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
e9e0: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
e9f0: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
ea00: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
ea10: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
ea20: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
ea30: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
ea40: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
ea50: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
ea60: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
ea70: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
ea80: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
ea90: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
eaa0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
eab0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
eac0: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
ead0: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
eae0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
eaf0: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
eb00: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
eb10: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
eb20: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
eb30: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
eb40: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
eb50: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
eb60: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
eb70: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
eb80: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
eb90: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
eba0: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
ebb0: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
ebc0: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
ebd0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
ebe0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
ebf0: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
ec00: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
ec10: 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65  t..  ** Those be
ec20: 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73  low are for vers
ec30: 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65  ion 3 and greate
ec40: 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  r..  */.  int (*
ec50: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xSetSystemCall)(
ec60: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
ec70: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
ec80: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
ec90: 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33  _ptr);.  sqlite3
eca0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78  _syscall_ptr (*x
ecb0: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  GetSystemCall)(s
ecc0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ecd0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
ece0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28  .  const char *(
ecf0: 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c  *xNextSystemCall
ed00: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ed10: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
ed20: 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  e);.  /*.  ** Th
ed30: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
ed40: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
ed50: 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74  1 through 3 of t
ed60: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
ed70: 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66  ject..  ** New f
ed80: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
ed90: 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  ended in future 
eda0: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
edb0: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
edc0: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
edd0: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
ede0: 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d  happens. .  */.}
edf0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
ee00: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
ee10: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
ee20: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
ee30: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
ee40: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
ee50: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
ee60: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
ee70: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
ee80: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
ee90: 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20  ] object.  They 
eea0: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
eeb0: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
eec0: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
eed0: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
eee0: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
eef0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
ef00: 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
ef10: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
ef20: 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
ef30: 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
ef40: 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
ef50: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
ef60: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
ef70: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
ef80: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61  s whether the na
ef90: 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73  med directory is
efa0: 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61   both readable a
efb0: 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28  nd writable.** (
efc0: 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
efd0: 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20  if files can be 
efe0: 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20  added, removed, 
eff0: 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68  and renamed with
f000: 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74  in.** the direct
f010: 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ory)..** The SQL
f020: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
f030: 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73  RITE constant is
f040: 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20   currently used 
f050: 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b  only by the.** [
f060: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
f070: 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68  tory pragma], th
f080: 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20  ough this could 
f090: 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
f0a0: 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
f0b0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68   SQLite..** With
f0c0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
f0d0: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
f0e0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
f0f0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
f100: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20  le is readable. 
f110: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
f120: 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74  SS_READ constant
f130: 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79   is.** currently
f140: 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20   unused, though 
f150: 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64  it might be used
f160: 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
f170: 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
f180: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
f190: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
f1a0: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
f1b0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
f1c0: 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55  ADWRITE 1   /* U
f1d0: 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65  sed by PRAGMA te
f1e0: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
f1f0: 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ry */.#define SQ
f200: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f210: 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75        2   /* Unu
f220: 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
f230: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
f240: 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56  r the xShmLock V
f250: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
f260: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
f270: 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74  nstants define t
f280: 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69  he various locki
f290: 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  ng operations.**
f2a0: 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20   allowed by the 
f2b0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
f2c0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  of [sqlite3_io_m
f2d0: 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a  ethods].  The.**
f2e0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74   following are t
f2f0: 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f  he only legal co
f300: 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c  mbinations of fl
f310: 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  ags to the.** xS
f320: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a  hmLock method:.*
f330: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
f340: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
f350: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
f360: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
f370: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
f380: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
f390: 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  LUSIVE.** <li>  
f3a0: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
f3b0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
f3c0: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <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 45 58   | SQLITE_SHM_EX
f3f0: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e  CLUSIVE.** </ul>
f400: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f  .**.** When unlo
f410: 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20  cking, the same 
f420: 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53  SHARED or EXCLUS
f430: 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65  IVE flag must be
f440: 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20   supplied as.** 
f450: 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65  was given on the
f460: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c   corresponding l
f470: 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ock.  .**.** The
f480: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
f490: 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20   can transition 
f4a0: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
f4b0: 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a   and SHARED or.*
f4c0: 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  * between unlock
f4d0: 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ed and EXCLUSIVE
f4e0: 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61  .  It cannot tra
f4f0: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
f500: 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58  SHARED.** and EX
f510: 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66  CLUSIVE..*/.#def
f520: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  ine SQLITE_SHM_U
f530: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64  NLOCK       1.#d
f540: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
f550: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a  _LOCK         2.
f560: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
f570: 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  HM_SHARED       
f580: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
f590: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20  _SHM_EXCLUSIVE  
f5a0: 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    8../*.** CAPI3
f5b0: 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68  REF: Maximum xSh
f5c0: 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a  mLock index.**.*
f5d0: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
f5e0: 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65  ethod on [sqlite
f5f0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61  3_io_methods] ma
f600: 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20  y use values.** 
f610: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
f620: 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  is upper bound a
f630: 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61  s its "offset" a
f640: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
f650: 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
f660: 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74   never attempt t
f670: 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c  o acquire or rel
f680: 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f  ease a.** lock o
f690: 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72  utside of this r
f6a0: 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ange.*/.#define 
f6b0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b  SQLITE_SHM_NLOCK
f6c0: 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a          8.../*.*
f6d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
f6e0: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
f6f0: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
f700: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
f710: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
f720: 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
f730: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
f740: 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ary.  ^The sqlit
f750: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
f760: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
f770: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
f780: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
f790: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
f7a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
f7b0: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
f7c0: 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74  s are designed t
f7d0: 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73  o aid in process
f7e0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
f7f0: 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20  and.** shutdown 
f800: 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  on embedded syst
f810: 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f  ems.  Workstatio
f820: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75  n applications u
f830: 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e  sing.** SQLite n
f840: 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e  ormally do not n
f850: 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69  eed to invoke ei
f860: 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f  ther of these ro
f870: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  utines..**.** A 
f880: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f890: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
f8a0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
f8b0: 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
f8c0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
f8d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f8e0: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
f8f0: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
f900: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
f910: 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
f920: 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
f930: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f940: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
f950: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
f960: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f970: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f  shutdown().  ^(O
f980: 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
f990: 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
f9a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f9b0: 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
f9c0: 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
f9d0: 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
f9e0: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
f9f0: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  s.)^.**.** A cal
fa00: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
fa10: 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65  tdown() is an "e
fa20: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
fa30: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
fa40: 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  t.** call to sql
fa50: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
fa60: 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73  since the last s
fa70: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fa80: 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20  e().  ^(Only.** 
fa90: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
faa0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
fab0: 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79  tdown() does any
fac0: 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f   deinitializatio
fad0: 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20  n..** All other 
fae0: 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73  valid calls to s
faf0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fb00: 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  ) are harmless n
fb10: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  o-ops.)^.**.** T
fb20: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
fb30: 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63  alize() interfac
fb40: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c  e is threadsafe,
fb50: 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75   but sqlite3_shu
fb60: 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f  tdown().** is no
fb70: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
fb80: 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72  shutdown() inter
fb90: 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62  face must only b
fba0: 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a  e called from a.
fbb0: 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  ** single thread
fbc0: 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74  .  All open [dat
fbd0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
fbe0: 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65  s] must be close
fbf0: 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68  d and all.** oth
fc00: 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72  er SQLite resour
fc10: 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c  ces must be deal
fc20: 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f  located prior to
fc30: 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
fc40: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
fc50: 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
fc60: 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69  er things, ^sqli
fc70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fc80: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
fc90: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
fca0: 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e  ).  Similarly, ^
fcb0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fcc0: 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b  ().** will invok
fcd0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
fce0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
fcf0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fd00: 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
fd10: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
fd20: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e  on success..** ^
fd30: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
fd40: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
fd50: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
fd60: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
fd70: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
fd80: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
fd90: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
fda0: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
fdb0: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
fdc0: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
fdd0: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
fde0: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
fdf0: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
fe00: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
fe10: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
fe20: 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
fe30: 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
fe40: 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
fe50: 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
fe60: 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
fe70: 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
fe80: 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
fe90: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
fea0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
feb0: 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
fec0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
fed0: 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
fee0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fef0: 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
ff00: 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
ff10: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
ff20: 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
ff30: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
ff40: 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
ff50: 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
ff60: 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
ff70: 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20  ady.  ^However, 
ff80: 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
ff90: 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
ffa0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
ffb0: 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
ffc0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
ffd0: 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
ffe0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
fff0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
10000 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
10010 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
10020 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
10030 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10040 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
10050 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
10060 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
10070 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
10080 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
10090 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
100a0 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
100b0 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
100c0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
100d0 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
100e0 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
100f0 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
10100 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
10110 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
10120 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
10130 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
10140 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
10150 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
10160 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
10170 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
10180 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
10190 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
101a0 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
101b0 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
101c0 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
101d0 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
101e0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
101f0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
10200 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
10210 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
10220 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
10230 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
10240 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
10250 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
10260 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
10270 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
10280 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
10290 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
102a0 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
102b0 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
102c0 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
102d0 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
102e0 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
102f0 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
10300 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
10310 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
10320 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
10330 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
10340 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
10350 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
10360 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
10370 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
10380 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
10390 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
103a0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
103b0 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
103c0 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
103d0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
103e0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
103f0 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
10400 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
10410 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
10420 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
10430 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
10440 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10450 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
10460 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
10470 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
10480 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
10490 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
104a0 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
104b0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
104c0 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
104d0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
104e0 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
104f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
10500 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
10510 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
10520 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
10530 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
10540 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
10550 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69  compiled for Uni
10560 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f  x, Windows, or O
10570 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75  S/2..** When [cu
10580 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75  stom builds | bu
10590 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c  ilt for other pl
105a0 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69  atforms].** (usi
105b0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
105c0 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69  S_OTHER=1] compi
105d0 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
105e0 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
105f0 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
10600 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
10610 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
10620 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10630 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
10640 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
10650 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
10660 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
10670 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
10680 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
10690 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
106a0 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ust return [SQLI
106b0 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
106c0 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
106d0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
106e0 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
106f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e  /.int sqlite3_in
10700 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a  itialize(void);.
10710 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
10720 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  down(void);.int 
10730 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10740 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
10750 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b  e3_os_end(void);
10760 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10770 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68  : Configuring Th
10780 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
10790 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
107a0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
107b0 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
107c0 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e   make global con
107d0 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
107e0 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20  anges to SQLite 
107f0 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65  in order to tune
10800 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73   SQLite to the s
10810 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
10820 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
10830 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ion.  The defaul
10840 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
10850 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
10860 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69  or most.** appli
10870 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74  cations and so t
10880 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
10890 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73  sually not neces
108a0 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20  sary.  It is.** 
108b0 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70  provided to supp
108c0 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61  ort rare applica
108d0 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75  tions with unusu
108e0 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  al needs..**.** 
108f0 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  <b>The sqlite3_c
10900 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
10910 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
10920 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63 61  afe. The applica
10930 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73  tion.** must ens
10940 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
10950 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
10960 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
10970 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
10980 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
10990 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
109a0 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a  nning.</b>.**.**
109b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
109c0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 0a  fig() interface.
109d0 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69  ** may only be i
109e0 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20  nvoked prior to 
109f0 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69  library initiali
10a00 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  zation using.** 
10a10 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
10a20 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
10a30 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c  shutdown by [sql
10a40 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
10a50 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
10a60 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c  _config() is cal
10a70 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
10a80 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
10a90 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b   and before.** [
10aa0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10ab0 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c  ()] then it will
10ac0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
10ad0 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  ISUSE..** Note, 
10ae0 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73  however, that ^s
10af0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10b00 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73  can be called as
10b10 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
10b20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
10b30 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
10b40 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65  -defined [sqlite
10b50 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a  3_os_init()]..**
10b60 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
10b70 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
10b80 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e  3_config() is an
10b90 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e   integer.** [con
10ba0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10bb0 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
10bc0 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
10bd0 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
10be0 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
10bf0 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
10c00 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
10c10 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
10c20 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  e [configuration
10c30 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
10c40 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10c50 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61  t..**.** ^When a
10c60 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10c70 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
10c80 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
10c90 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
10ca0 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  K]..** ^If the o
10cb0 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
10cc0 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
10cd0 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
10ce0 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
10cf0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
10d00 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
10d10 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
10d20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
10d30 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
10d40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10d50 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
10d60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
10d70 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
10d80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
10d90 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
10da0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
10db0 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
10dc0 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
10dd0 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
10de0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
10df0 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
10e00 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
10e10 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10e20 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
10e30 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
10e40 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
10e50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10e60 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
10e70 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
10e80 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
10e90 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
10ea0 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
10eb0 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
10ec0 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
10ed0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
10ee0 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
10ef0 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
10f00 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
10f10 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
10f20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
10f30 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
10f40 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
10f50 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
10f60 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
10f70 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
10f80 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
10f90 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
10fa0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
10fb0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10fc0 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
10fd0 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
10fe0 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
10ff0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
11000 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  ccessful..*/.int
11010 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
11020 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
11030 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
11040 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
11050 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
11060 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
11070 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
11080 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
11090 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
110a0 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
110b0 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
110c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
110d0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
110e0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
110f0 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
11100 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
11110 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
11120 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
11130 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
11140 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
11150 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
11160 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11170 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
11180 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11190 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
111a0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
111b0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
111c0 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
111d0 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
111e0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
111f0 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
11200 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
11210 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
11220 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
11230 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
11240 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
11250 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
11260 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
11270 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
11280 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
11290 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
112a0 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
112b0 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
112c0 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
112d0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
112e0 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
112f0 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
11300 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
11310 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
11320 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
11330 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
11340 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
11350 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
11360 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
11370 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
11380 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
11390 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
113a0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
113b0 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
113c0 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
113d0 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
113e0 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
113f0 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
11400 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
11410 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
11420 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
11430 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
11440 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11450 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
11460 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
11470 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
11480 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
11490 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
114a0 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
114b0 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
114c0 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
114d0 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
114e0 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20  , xRealloc, and 
114f0 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
11500 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
11510 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  .** malloc(), re
11520 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
11530 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
11540 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
11550 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51   library..** ^SQ
11560 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
11570 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
11580 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
11590 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
115a0 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
115b0 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
115c0 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
115d0 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
115e0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
115f0 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
11600 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
11610 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
11620 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
11630 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
11640 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
11650 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
11660 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
11670 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
11680 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
11690 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
116a0 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
116b0 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
116c0 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
116d0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
116e0 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
116f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
11700 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
11710 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
11720 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
11730 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
11740 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
11750 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
11760 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
11770 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
11780 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
11790 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
117a0 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
117b0 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
117c0 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
117d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
117e0 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
117f0 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
11800 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
11810 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
11820 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
11830 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
11840 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
11850 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
11860 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
11870 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
11880 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
11890 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
118a0 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
118b0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
118c0 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70  ator.  For examp
118d0 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
118e0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
118f0 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
11900 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
11910 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
11920 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
11930 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
11940 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
11950 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
11960 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
11970 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
11980 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
11990 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
119a0 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
119b0 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
119c0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
119d0 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
119e0 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
119f0 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
11a00 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
11a10 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
11a20 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
11a30 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
11a40 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
11a50 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
11a60 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
11a70 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
11a80 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
11a90 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
11aa0 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
11ab0 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
11ac0 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
11ad0 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
11ae0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
11af0 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
11b00 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
11b10 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
11b20 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
11b30 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
11b40 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
11b50 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
11b60 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
11b70 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11b80 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
11b90 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
11ba0 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
11bb0 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
11bc0 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
11bd0 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
11be0 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
11bf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
11c00 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
11c10 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
11c20 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
11c30 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
11c40 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
11c50 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
11c60 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
11c70 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
11c80 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
11c90 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
11ca0 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
11cb0 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
11cc0 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
11cd0 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
11ce0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
11cf0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
11d00 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
11d10 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
11d20 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
11d30 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
11d40 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
11d50 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
11d60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
11d70 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
11d80 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
11d90 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
11da0 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
11db0 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
11dc0 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
11dd0 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
11de0 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
11df0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
11e00 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
11e10 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
11e20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
11e30 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
11e40 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
11e50 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
11e60 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
11e70 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
11e80 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
11e90 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
11ea0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
11eb0 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
11ec0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11ed0 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
11ee0 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
11ef0 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
11f00 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
11f10 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
11f20 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
11f30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
11f40 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
11f50 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
11f60 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
11f70 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
11f80 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
11f90 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
11fa0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11fb0 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion}.**.** Thes
11fc0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
11fd0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
11fe0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
11ff0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
12000 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
12010 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
12020 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
12030 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12040 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
12050 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
12060 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
12070 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
12080 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
12090 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
120a0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
120b0 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
120c0 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
120d0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
120e0 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
120f0 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
12100 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  rom [sqlite3_con
12110 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
12120 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
12130 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68  call worked.  Th
12140 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
12150 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
12160 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
12170 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
12180 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
12190 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
121a0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
121b0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
121c0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
121d0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
121e0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
121f0 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
12200 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
12210 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
12220 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
12230 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
12240 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
12250 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
12260 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
12270 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74  ode] to Single-t
12280 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
12290 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
122a0 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
122b0 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
122c0 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
122d0 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
122e0 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
122f0 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
12300 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
12310 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12320 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
12330 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
12340 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
12350 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12360 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
12370 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
12380 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68  o change the [th
12390 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72  reading mode] fr
123a0 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a  om its default.*
123b0 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c  * value of Singl
123c0 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20  e-thread and so 
123d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
123e0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a  )] will return .
123f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
12400 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
12410 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
12420 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a  IG_SINGLETHREAD.
12430 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
12440 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
12450 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12460 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
12470 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12480 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
12490 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
124a0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
124b0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
124c0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
124d0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
124e0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
124f0 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
12500 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
12510 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
12520 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
12530 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12540 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
12550 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
12560 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
12570 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
12580 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
12590 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
125a0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
125b0 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
125c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
125d0 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
125e0 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
125f0 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
12600 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
12610 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
12620 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
12630 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
12640 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
12650 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
12660 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
12670 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12680 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
12690 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
126a0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
126b0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
126c0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
126d0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
126e0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
126f0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12700 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
12710 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
12720 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
12730 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
12740 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
12750 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
12760 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
12770 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
12780 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
12790 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
127a0 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
127b0 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
127c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
127d0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d  NFIG_SERIALIZED]
127e0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
127f0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
12800 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
12810 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
12820 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
12830 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
12840 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
12850 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
12860 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
12870 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
12880 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
12890 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
128a0 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
128b0 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
128c0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
128d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
128e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
128f0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
12900 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
12910 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
12920 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
12930 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
12940 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
12950 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
12960 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
12970 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
12980 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
12990 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
129a0 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
129b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
129c0 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
129d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
129e0 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
129f0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
12a00 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
12a10 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
12a20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
12a30 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
12a40 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
12a50 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
12a60 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
12a70 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
12a80 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
12a90 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12aa0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
12ab0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
12ac0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
12ad0 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
12ae0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
12af0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
12b00 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
12b10 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
12b20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
12b30 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
12b40 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
12b50 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
12b60 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12b70 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
12b80 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12b90 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
12ba0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
12bb0 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
12bc0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
12bd0 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e  IG_MALLOC option
12be0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
12bf0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12c00 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
12c10 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
12c20 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12c30 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12c40 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
12c50 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
12c60 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
12c70 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
12c80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12c90 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
12ca0 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
12cb0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
12cc0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
12cd0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
12ce0 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
12cf0 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
12d00 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
12d10 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
12d20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12d30 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
12d40 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
12d50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12d60 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
12d70 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12d80 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12d90 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
12da0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
12db0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
12dc0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
12dd0 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69  G_GETMALLOC opti
12de0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12df0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12e00 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
12e10 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
12e20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12e30 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
12e40 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b  ucture..** The [
12e50 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12e60 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
12e70 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
12e80 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
12e90 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
12ea0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
12eb0 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
12ec0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
12ed0 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
12ee0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
12ef0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
12f00 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
12f10 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61  pper that simula
12f20 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tions memory all
12f30 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20  ocation failure 
12f40 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d  or.** tracks mem
12f50 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65  ory usage, for e
12f60 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  xample. </dd>.**
12f70 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12f80 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20  FIG_MEMSTATUS]] 
12f90 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12fa0 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
12fb0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
12fc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
12fd0 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b  TATUS option tak
12fe0 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
12ff0 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a  nt of type int,.
13000 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ** interpreted a
13010 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  s a boolean, whi
13020 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
13030 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
13040 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f  ction of.** memo
13050 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
13060 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e  atistics. ^(When
13070 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13080 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
13090 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74  e.** disabled, t
130a0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
130b0 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
130c0 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74  ecome non-operat
130d0 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
130e0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
130f0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
13100 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
13110 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
13120 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
13130 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
13140 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
13150 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
13160 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d  ite3_status64()]
13170 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  .**   </ul>)^.**
13180 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74   ^Memory allocat
13190 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
131a0 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
131b0 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c  fault unless SQL
131c0 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
131d0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
131e0 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
131f0 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61  S]=0 in which ca
13200 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  se memory.** all
13210 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
13220 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  cs are disabled 
13230 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  by default..** <
13240 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13250 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
13260 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  CH]] <dt>SQLITE_
13270 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
13280 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
13290 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
132a0 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70  CRATCH option sp
132b0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
132c0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a   memory buffer.*
132d0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  * that SQLite ca
132e0 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 63  n use for scratc
132f0 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65  h memory.  ^(The
13300 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
13310 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c  uments.** to SQL
13320 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
13330 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61  CH:  A pointer a
13340 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
13350 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ned memory buffe
13360 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  r from which the
13370 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
13380 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
13390 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
133a0 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
133b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
133c0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
133d0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
133e0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
133f0 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20  s (N).)^.** The 
13400 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
13410 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72  ust be a pointer
13420 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
13430 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20  igned buffer.** 
13440 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
13450 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
13460 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
13470 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74  l not use more t
13480 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20  han one scratch 
13490 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65  buffers per thre
134a0 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ad..** ^SQLite w
134b0 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73  ill never reques
134c0 74 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66  t a scratch buff
134d0 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20  er that is more 
134e0 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20  than 6.** times 
134f0 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
13500 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53  e size..** ^If S
13510 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
13520 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  s additional.** 
13530 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
13540 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
13550 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
13560 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13570 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
13580 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
13590 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
135a0 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
135b0 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a  ry needed.<p>.**
135c0 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69   ^When the appli
135d0 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20  cation provides 
135e0 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63  any amount of sc
135f0 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69  ratch memory usi
13600 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  ng.** SQLITE_CON
13610 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c  FIG_SCRATCH, SQL
13620 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63  ite avoids unnec
13630 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20  essary large.** 
13640 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c  [sqlite3_malloc|
13650 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  heap allocations
13660 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68  ]..** This can h
13670 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f  elp [Robson proo
13680 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79  f|prevent memory
13690 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
136a0 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61  ures] due to hea
136b0 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69  p.** fragmentati
136c0 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79  on in low-memory
136d0 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
136e0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
136f0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13700 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
13710 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13720 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
13730 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
13740 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13750 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  CHE option speci
13760 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f  fies a memory po
13770 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  ol.** that SQLit
13780 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68  e can use for th
13790 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
137a0 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
137b0 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63  efault page.** c
137c0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
137d0 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63  ion.  .** This c
137e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
137f0 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69  ion is a no-op i
13800 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
13810 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
13820 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
13830 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
13840 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
13850 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
13860 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20  ..** ^There are 
13870 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
13880 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
13890 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f  _PAGECACHE: A po
138a0 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79  inter to.** 8-by
138b0 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72  te aligned memor
138c0 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73 69  y (pMem), the si
138d0 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
138e0 63 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c  cache line (sz),
138f0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  .** and the numb
13900 65 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e 65  er of cache line
13910 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a  s (N)..** The sz
13920 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
13930 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20   be the size of 
13940 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
13950 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20  base page.** (a 
13960 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74  power of two bet
13970 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35  ween 512 and 655
13980 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78  36) plus some ex
13990 74 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 61  tra bytes for ea
139a0 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
139b0 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  r.  ^The number 
139c0 6f 66 20 65 78 74 72 61 20 62 79 74 65 73 20 6e  of extra bytes n
139d0 65 65 64 65 64 20 62 79 20 74 68 65 20 70 61 67  eeded by the pag
139e0 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20  e header.** can 
139f0 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
13a00 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ing [SQLITE_CONF
13a10 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d  IG_PCACHE_HDRSZ]
13a20 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d  ..** ^It is harm
13a30 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d  less, apart from
13a40 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f   the wasted memo
13a50 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  ry,.** for the s
13a60 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  z parameter to b
13a70 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65  e larger than ne
13a80 63 65 73 73 61 72 79 2e 20 20 54 68 65 20 70 4d  cessary.  The pM
13a90 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d  em.** argument m
13aa0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
13ab0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
13ac0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
13ad0 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65  8-byte.** aligne
13ae0 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  d block of memor
13af0 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  y of at least sz
13b00 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72 77  *N bytes, otherw
13b10 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e  ise.** subsequen
13b20 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  t behavior is un
13b30 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65  defined..** ^Whe
13b40 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55  n pMem is not NU
13b50 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
13b60 73 74 72 69 76 65 20 74 6f 20 75 73 65 20 74 68  strive to use th
13b70 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
13b80 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20  d.** to satisfy 
13b90 70 61 67 65 20 63 61 63 68 65 20 6e 65 65 64 73  page cache needs
13ba0 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74  , falling back t
13bb0 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
13bc0 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67  c()] if.** a pag
13bd0 65 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73 20  e cache line is 
13be0 6c 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20 62  larger than sz b
13bf0 79 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f  ytes or if all o
13c00 66 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66 65  f the pMem buffe
13c10 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74 65  r.** is exhauste
13c20 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69  d..** ^If pMem i
13c30 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
13c40 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65  non-zero, then e
13c50 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
13c60 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20  nection.** does 
13c70 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20  an initial bulk 
13c80 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70  allocation for p
13c90 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
13ca0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
13cb0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66  3_malloc()] suff
13cc0 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61 63  icient for N cac
13cd0 68 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69 73  he lines if N is
13ce0 20 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20   positive or.** 
13cf0 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65 73  of -1024*N bytes
13d00 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76   if N is negativ
13d10 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69 6f  e, . ^If additio
13d20 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
13d30 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
13d40 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
13d50 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
13d60 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c  e initial.** all
13d70 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51  ocation, then SQ
13d80 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
13d90 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
13da0 73 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20 65  separately for e
13db0 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  ach.** additiona
13dc0 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f  l cache line. </
13dd0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13de0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d  TE_CONFIG_HEAP]]
13df0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13e00 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20  IG_HEAP</dt>.** 
13e10 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
13e20 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74  _CONFIG_HEAP opt
13e30 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
13e40 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
13e50 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51  ffer .** that SQ
13e60 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f  Lite will use fo
13e70 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
13e80 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  amic memory allo
13e90 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20  cation needs.** 
13ea0 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
13eb0 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51  vided for by [SQ
13ec0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
13ed0 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c  TCH] and.** [SQL
13ee0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
13ef0 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53  ACHE]..** ^The S
13f00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
13f10 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  P option is only
13f20 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
13f30 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
13f40 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 20  .** with either 
13f50 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
13f60 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49  EMSYS3] or [SQLI
13f70 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
13f80 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  5] and returns.*
13f90 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
13fa0 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65   if invoked othe
13fb0 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65  rwise..** ^There
13fc0 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
13fd0 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43  ents to SQLITE_C
13fe0 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41  ONFIG_HEAP:.** A
13ff0 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
14000 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
14010 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e  memory,.** the n
14020 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
14030 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66  n the memory buf
14040 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e  fer, and the min
14050 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
14060 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  size..** ^If the
14070 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
14080 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
14090 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  er) is NULL, the
140a0 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73  n SQLite reverts
140b0 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73  .** to using its
140c0 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
140d0 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73  allocator (the s
140e0 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69  ystem malloc() i
140f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a  mplementation),.
14100 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70  ** undoing any p
14110 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20  rior invocation 
14120 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  of [SQLITE_CONFI
14130 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20  G_MALLOC].  ^If 
14140 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f  the.** memory po
14150 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
14160 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72  L then the alter
14170 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a  native memory.**
14180 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e   allocator is en
14190 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20  gaged to handle 
141a0 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d  all of SQLites m
141b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
141c0 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66   needs..** The f
141d0 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
141e0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
141f0 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  ) must be aligne
14200 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  d to an 8-byte.*
14210 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  * boundary or su
14220 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
14230 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  r of SQLite will
14240 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   be undefined..*
14250 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  * The minimum al
14260 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73  location size is
14270 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32   capped at 2**12
14280 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c  . Reasonable val
14290 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d  ues.** for the m
142a0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
142b0 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20  n size are 2**5 
142c0 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64  through 2**8.</d
142d0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
142e0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d  E_CONFIG_MUTEX]]
142f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14300 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  IG_MUTEX</dt>.**
14310 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
14320 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
14330 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14340 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
14350 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69  hich is a.** poi
14360 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
14370 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
14380 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
14390 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
143a0 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
143b0 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74  ecifies alternat
143c0 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
143d0 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
143e0 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c  be used.** in pl
143f0 61 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f  ace the mutex ro
14400 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
14410 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
14420 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
14430 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
14440 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
14450 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
14460 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
14470 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
14480 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
14490 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
144a0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
144b0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
144c0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
144d0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
144e0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
144f0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
14500 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
14510 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
14520 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
14530 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
14540 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
14550 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
14560 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
14570 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14580 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
14590 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
145a0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
145b0 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
145c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
145d0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20  NFIG_GETMUTEX]] 
145e0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
145f0 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
14600 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14620 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65  UTEX option take
14630 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14640 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
14650 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14660 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
14670 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
14680 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
14690 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
146a0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
146b0 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
146c0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
146d0 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
146e0 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
146f0 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
14700 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
14710 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
14720 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
14730 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
14740 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
14750 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
14760 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
14770 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
14780 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
14790 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
147a0 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69  mple.   ^If SQLi
147b0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
147c0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
147d0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
147e0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
147f0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
14800 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
14810 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
14820 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
14830 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
14840 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
14850 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
14860 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
14870 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
14880 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
14890 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
148a0 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
148b0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
148c0 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
148d0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
148e0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74  _LOOKASIDE]] <dt
148f0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
14900 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
14910 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
14920 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
14930 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  IDE option takes
14940 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
14950 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hat determine.**
14960 20 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a   the default siz
14970 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  e of lookaside m
14980 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64  emory on each [d
14990 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
149a0 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  on]..** The firs
149b0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  t argument is th
149c0 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
149d0 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
149e0 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20  er slot and the 
149f0 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75  second is the nu
14a00 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
14a10 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61   allocated to ea
14a20 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
14a30 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c  ection.)^  ^(SQL
14a40 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
14a50 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65  SIDE.** sets the
14a60 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
14a70 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
14a80 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
14a90 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
14aa0 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71  ** option to [sq
14ab0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
14ac0 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  )] can be used t
14ad0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
14ae0 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67  kaside.** config
14af0 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  uration on indiv
14b00 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e  idual connection
14b10 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s.)^ </dd>.**.**
14b20 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14b30 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  _PCACHE2]] <dt>S
14b40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14b50 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
14b60 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
14b70 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70  ONFIG_PCACHE2 op
14b80 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14b90 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
14ba0 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  ch is .** a poin
14bb0 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74  ter to an [sqlit
14bc0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
14bd0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  s2] object.  Thi
14be0 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
14bf0 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66  es.** the interf
14c00 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  ace to a custom 
14c10 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
14c20 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20  mentation.)^.** 
14c30 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
14c40 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
14c50 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
14c60 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64  ods2] object.</d
14c70 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14c80 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
14c90 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
14ca0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
14cb0 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
14cc0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
14cd0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f  FIG_GETPCACHE2 o
14ce0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14cf0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
14d00 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
14d10 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74  ter to an [sqlit
14d20 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
14d30 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  s2] object.  SQL
14d40 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a  ite copies of.**
14d50 20 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 67   the current pag
14d60 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
14d70 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
14d80 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
14d90 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14da0 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74  CONFIG_LOG]] <dt
14db0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
14dc0 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
14dd0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14de0 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20  G_LOG option is 
14df0 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
14e00 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20  e the SQLite.** 
14e10 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f  global [error lo
14e20 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c  g]..** (^The SQL
14e30 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
14e40 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
14e50 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69  arguments: a poi
14e60 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e  nter to a.** fun
14e70 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c  ction with a cal
14e80 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76  l signature of v
14e90 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  oid(*)(void*,int
14ea0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a  ,const char*), .
14eb0 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72  ** and a pointer
14ec0 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68   to void. ^If th
14ed0 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
14ee0 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  er is not NULL, 
14ef0 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64  it is.** invoked
14f00 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67   by [sqlite3_log
14f10 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65  ()] to process e
14f20 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e  ach logging even
14f30 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66  t.  ^If the.** f
14f40 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
14f50 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71  is NULL, the [sq
14f60 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74  lite3_log()] int
14f70 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61  erface becomes a
14f80 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20   no-op..** ^The 
14f90 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61  void pointer tha
14fa0 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  t is the second 
14fb0 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49  argument to SQLI
14fc0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73  TE_CONFIG_LOG is
14fd0 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75  .** passed throu
14fe0 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
14ff0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
15000 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
15010 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
15020 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72  unction whenever
15030 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69   that function i
15040 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65  s invoked.  ^The
15050 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
15060 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67  r to.** the logg
15070 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  er function is a
15080 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72   copy of the fir
15090 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
150a0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
150b0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  g.** [sqlite3_lo
150c0 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73  g()] call and is
150d0 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20   intended to be 
150e0 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  a [result code] 
150f0 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64  or an.** [extend
15100 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e  ed result code].
15110 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72    ^The third par
15120 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f  ameter passed to
15130 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a   the logger is.*
15140 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66  * log message af
15150 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76  ter formatting v
15160 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ia [sqlite3_snpr
15170 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  intf()]..** The 
15180 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69  SQLite logging i
15190 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
151a0 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c  reentrant; the l
151b0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a  ogger function.*
151c0 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  * supplied by th
151d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
151e0 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e  st not invoke an
151f0 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
15200 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74  ce..** In a mult
15210 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  i-threaded appli
15220 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c  cation, the appl
15230 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
15240 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
15250 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  on must be threa
15260 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  dsafe. </dd>.**.
15270 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15280 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c  IG_URI]] <dt>SQL
15290 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a  ITE_CONFIG_URI.*
152a0 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49  * <dd>^(The SQLI
152b0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70  TE_CONFIG_URI op
152c0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
152d0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
152e0 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20  type int..** If 
152f0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55  non-zero, then U
15300 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
15310 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e  lobally enabled.
15320 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
15330 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68  r is zero,.** th
15340 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  en URI handling 
15350 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
15360 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20  bled.)^ ^If URI 
15370 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
15380 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c  ally.** enabled,
15390 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70   all filenames p
153a0 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
153b0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
153c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a  te3_open_v2()],.
153d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
153e0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
153f0 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
15400 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
15410 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
15420 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
15430 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
15440 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
15450 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
15460 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
15470 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
15480 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
15490 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20   opened. ^If it 
154a0 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
154b0 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20  bled, filenames 
154c0 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65  are.** only inte
154d0 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20  rpreted as URIs 
154e0 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  if the SQLITE_OP
154f0 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73  EN_URI flag is s
15500 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64  et when the.** d
15510 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15520 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28  on is opened. ^(
15530 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20  By default, URI 
15540 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
15550 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64  ally.** disabled
15560 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
15570 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67  lue may be chang
15580 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20  ed by compiling 
15590 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
155a0 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d  ITE_USE_URI] sym
155b0 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a  bol defined.)^.*
155c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
155d0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
155e0 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53  DEX_SCAN]] <dt>S
155f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
15600 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
15610 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
15620 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
15630 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f  ING_INDEX_SCAN o
15640 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
15650 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20  ngle integer.** 
15660 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
15670 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
15680 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72   a boolean in or
15690 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  der to enable or
156a0 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20   disable.** the 
156b0 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
156c0 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
156d0 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20   table scans in 
156e0 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69  the query optimi
156f0 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  zer..** ^The def
15700 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20  ault setting is 
15710 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79  determined.** by
15720 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c   the [SQLITE_ALL
15730 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  OW_COVERING_INDE
15740 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d  X_SCAN] compile-
15750 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20  time option, or 
15760 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68  is "on".** if th
15770 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
15780 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  option is omitte
15790 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74  d..** The abilit
157a0 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65  y to disable the
157b0 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
157c0 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c   indices for ful
157d0 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a  l table scans.**
157e0 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65   is because some
157f0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64   incorrectly cod
15800 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63  ed legacy applic
15810 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c  ations might mal
15820 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e  function.** when
15830 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
15840 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50  n is enabled.  P
15850 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69  roviding the abi
15860 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62  lity to.** disab
15870 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  le the optimizat
15880 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f  ion allows the o
15890 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c  lder, buggy appl
158a0 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20  ication code to 
158b0 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20  work.** without 
158c0 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68  change even with
158d0 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
158e0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
158f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15900 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49  _PCACHE]] [[SQLI
15910 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
15920 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  CHE]].** <dt>SQL
15930 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
15940 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e  E and SQLITE_CON
15950 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a  FIG_GETPCACHE.**
15960 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69   <dd> These opti
15970 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65  ons are obsolete
15980 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20   and should not 
15990 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63  be used by new c
159a0 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65  ode..** They are
159b0 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61   retained for ba
159c0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
159d0 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f  ility but are no
159e0 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64  w no-ops..** </d
159f0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15a00 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d  E_CONFIG_SQLLOG]
15a10 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
15a20 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a  CONFIG_SQLLOG.**
15a30 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
15a40 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
15a50 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20  le if sqlite is 
15a60 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
15a70 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
15a80 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d  BLE_SQLLOG] pre-
15a90 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
15aa0 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72  defined. The fir
15ab0 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  st argument shou
15ac0 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74  ld.** be a point
15ad0 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  er to a function
15ae0 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29   of type void(*)
15af0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
15b00 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
15b10 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
15b20 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79   should be of ty
15b30 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20  pe (void*). The 
15b40 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
15b50 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61  ked by the libra
15b60 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73  ry.** in three s
15b70 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74  eparate circumst
15b80 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65  ances, identifie
15b90 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70  d by the value p
15ba0 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20  assed as the.** 
15bb0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15bc0 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  . If the fourth 
15bd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20  parameter is 0, 
15be0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
15bf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
15c00 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
15c10 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61  cond argument ha
15c20 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e  s just been open
15c30 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72  ed. The third ar
15c40 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73  gument.** points
15c50 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e   to a buffer con
15c60 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65  taining the name
15c70 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74   of the main dat
15c80 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74  abase file. If t
15c90 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
15ca0 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65  ameter is 1, the
15cb0 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
15cc0 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69  ent that the thi
15cd0 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
15ce0 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75  points to has ju
15cf0 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64  st been executed
15d00 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75  . Or, if the fou
15d10 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
15d20 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20   2, then.** the 
15d30 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67  connection being
15d40 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
15d50 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15d60 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e  is being closed.
15d70 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   The.** third pa
15d80 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65  rameter is passe
15d90 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63  d NULL In this c
15da0 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ase.  An example
15db0 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a   of using this.*
15dc0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
15dd0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65  option can be se
15de0 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f  en in the "test_
15df0 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65  sqllog.c" source
15e00 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20   file in.** the 
15e10 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65  canonical SQLite
15e20 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64   source tree.</d
15e30 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15e40 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
15e50 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
15e60 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
15e70 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49  IZE.** <dd>^SQLI
15e80 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
15e90 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34  IZE takes two 64
15ea0 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71  -bit integer (sq
15eb0 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c  lite3_int64) val
15ec0 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ues.** that are 
15ed0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70  the default mmap
15ee0 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65   size limit (the
15ef0 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
15f00 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   for.** [PRAGMA 
15f10 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20  mmap_size]) and 
15f20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  the maximum allo
15f30 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  wed mmap size li
15f40 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  mit..** ^The def
15f50 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e  ault setting can
15f60 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62   be overridden b
15f70 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  y each database 
15f80 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67  connection using
15f90 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b  .** either the [
15fa0 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
15fb0 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79  ] command, or by
15fc0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53   using the.** [S
15fd0 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
15fe0 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74  _SIZE] file cont
15ff0 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69  rol.  ^(The maxi
16000 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
16010 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65   size.** will be
16020 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
16030 74 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 79  ted if necessary
16040 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73   so that it does
16050 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a   not exceed the.
16060 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
16070 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a  maximum mmap siz
16080 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  e set by the.** 
16090 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50  [SQLITE_MAX_MMAP
160a0 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SIZE] compile-t
160b0 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a  ime option.)^.**
160c0 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75   ^If either argu
160d0 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74  ment to this opt
160e0 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ion is negative,
160f0 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d   then that argum
16100 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65  ent is.** change
16110 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65  d to its compile
16120 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a  -time default..*
16130 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16140 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
16150 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
16160 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
16170 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64  _HEAPSIZE.** <dd
16180 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
16190 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
161a0 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  ZE option is onl
161b0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53  y available if S
161c0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
161d0 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73  iled for Windows
161e0 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
161f0 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20  E_WIN32_MALLOC] 
16200 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61  pre-processor ma
16210 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20  cro.** defined. 
16220 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  ^SQLITE_CONFIG_W
16230 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61  IN32_HEAPSIZE ta
16240 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73  kes a 32-bit uns
16250 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61  igned integer va
16260 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63  lue.** that spec
16270 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75  ifies the maximu
16280 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72  m size of the cr
16290 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a  eated heap..**.*
162a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
162b0 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d  G_PCACHE_HDRSZ]]
162c0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
162d0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
162e0 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  SZ.** <dd>^The S
162f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16300 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e  CHE_HDRSZ option
16310 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16320 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
16330 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
16340 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e  to an integer an
16350 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68  d writes into th
16360 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e  at integer the n
16370 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a  umber of extra.*
16380 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65  * bytes per page
16390 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61   required for ea
163a0 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49  ch page in [SQLI
163b0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
163c0 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f  CHE]..** The amo
163d0 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61  unt of extra spa
163e0 63 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20  ce required can 
163f0 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67  change depending
16400 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72   on the compiler
16410 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74  ,.** target plat
16420 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65  form, and SQLite
16430 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20   version..**.** 
16440 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16450 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  PMASZ]].** <dt>S
16460 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
16470 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  SZ.** <dd>^The S
16480 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
16490 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
164a0 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
164b0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
164c0 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  n unsigned integ
164d0 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20  er and sets the 
164e0 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a  "Minimum PMA Siz
164f0 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69  e" for the multi
16500 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74  threaded.** sort
16510 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67  er to that integ
16520 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  er.  The default
16530 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a   minimum PMA Siz
16540 65 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a  e is set by the.
16550 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45  ** [SQLITE_SORTE
16560 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65  R_PMASZ] compile
16570 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e  -time option.  N
16580 65 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c  ew threads are l
16590 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65  aunched.** to he
165a0 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65  lp with sort ope
165b0 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c  rations when mul
165c0 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69  tithreaded sorti
165d0 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64  ng.** is enabled
165e0 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41   (using the [PRA
165f0 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d  GMA threads] com
16600 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d  mand) and the am
16610 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a  ount of content.
16620 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20  ** to be sorted 
16630 65 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65  exceeds the page
16640 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20   size times the 
16650 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a  minimum of the.*
16660 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f  * [PRAGMA cache_
16670 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e  size] setting an
16680 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a  d this value..**
16690 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
166a0 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
166b0 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  LL]].** <dt>SQLI
166c0 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
166d0 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e  NL_SPILL.** <dd>
166e0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
166f0 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
16700 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  L option takes a
16710 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
16720 72 20 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d  r which.** becom
16730 65 73 20 74 68 65 20 5b 73 74 61 74 65 6d 65 6e  es the [statemen
16740 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c  t journal] spill
16750 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65 73 68 6f  -to-disk thresho
16760 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d  ld.  .** [Statem
16770 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72  ent journals] ar
16780 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79  e held in memory
16790 20 75 6e 74 69 6c 20 74 68 65 69 72 20 73 69 7a   until their siz
167a0 65 20 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20  e (in bytes).** 
167b0 65 78 63 65 65 64 73 20 74 68 69 73 20 74 68 72  exceeds this thr
167c0 65 73 68 6f 6c 64 2c 20 61 74 20 77 68 69 63 68  eshold, at which
167d0 20 70 6f 69 6e 74 20 74 68 65 79 20 61 72 65 20   point they are 
167e0 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e  written to disk.
167f0 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65 20 74 68  .** Or if the th
16800 72 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73  reshold is -1, s
16810 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
16820 73 20 61 72 65 20 61 6c 77 61 79 73 20 68 65 6c  s are always hel
16830 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c 79  d.** exclusively
16840 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53   in memory..** S
16850 69 6e 63 65 20 6d 61 6e 79 20 73 74 61 74 65 6d  ince many statem
16860 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76  ent journals nev
16870 65 72 20 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c  er become large,
16880 20 73 65 74 74 69 6e 67 20 74 68 65 20 73 70 69   setting the spi
16890 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20  ll.** threshold 
168a0 74 6f 20 61 20 76 61 6c 75 65 20 73 75 63 68 20  to a value such 
168b0 61 73 20 36 34 4b 69 42 20 63 61 6e 20 67 72 65  as 64KiB can gre
168c0 61 74 6c 79 20 72 65 64 75 63 65 20 74 68 65 20  atly reduce the 
168d0 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f  amount of.** I/O
168e0 20 72 65 71 75 69 72 65 64 20 74 6f 20 73 75 70   required to sup
168f0 70 6f 72 74 20 73 74 61 74 65 6d 65 6e 74 20 72  port statement r
16900 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  ollback..** The 
16910 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f  default value fo
16920 72 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69  r this setting i
16930 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
16940 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  the.** [SQLITE_S
16950 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63  TMTJRNL_SPILL] c
16960 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16970 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  on..** </dl>.*/.
16980 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16990 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
169a0 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
169b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
169c0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
169d0 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
169e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
169f0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
16a00 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
16a10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16a20 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
16a30 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
16a40 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
16a50 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16a60 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
16a70 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
16a80 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
16a90 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
16aa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
16ab0 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
16ac0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
16ad0 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
16ae0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16af0 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
16b00 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
16b10 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
16b20 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16b30 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
16b40 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
16b50 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
16b60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16b70 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
16b80 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
16b90 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
16ba0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
16bb0 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
16bc0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
16bd0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
16be0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16bf0 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
16c00 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
16c10 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
16c20 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
16c30 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
16c40 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
16c50 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
16c60 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
16c70 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
16c80 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
16c90 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
16ca0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16cb0 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
16cc0 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
16cd0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16ce0 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
16cf0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
16d00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16d10 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
16d20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
16d30 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
16d40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
16d50 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
16d60 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
16d70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16d80 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
16d90 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
16da0 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
16db0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16dc0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
16dd0 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
16de0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
16df0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16e00 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
16e10 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30  NG_INDEX_SCAN 20
16e20 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
16e30 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16e40 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32  G_SQLLOG       2
16e50 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76  1  /* xSqllog, v
16e60 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
16e70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
16e80 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f  AP_SIZE    22  /
16e90 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  * sqlite3_int64,
16ea0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
16eb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16ec0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
16ed0 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20  APSIZE      23  
16ee0 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a  /* int nByte */.
16ef0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16f00 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
16f10 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a  SZ        24  /*
16f20 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65   int *psz */.#de
16f30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16f40 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20  IG_PMASZ        
16f50 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e         25  /* un
16f60 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61  signed int szPma
16f70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16f80 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
16f90 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36  NL_SPILL      26
16fa0 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
16fb0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
16fc0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
16fd0 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
16fe0 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
16ff0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
17000 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
17010 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
17020 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
17030 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
17040 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
17050 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
17060 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
17070 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
17080 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
17090 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
170a0 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
170b0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
170c0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
170d0 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
170e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
170f0 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
17100 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
17110 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
17120 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
17130 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
17140 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
17150 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
17160 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
17170 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
17180 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
17190 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
171a0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
171b0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
171c0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
171d0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
171e0 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
171f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
17200 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
17210 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
17220 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
17230 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
17240 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
17250 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
17260 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
17270 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
17280 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
17290 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
172a0 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
172b0 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
172c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
172d0 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
172e0 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
172f0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
17300 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
17310 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
17320 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
17330 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
17340 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
17350 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
17360 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17370 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
17380 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
17390 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
173a0 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
173b0 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
173c0 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
173d0 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
173e0 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
173f0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
17400 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
17410 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
17420 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
17430 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
17440 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
17450 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
17460 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
17470 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
17480 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
17490 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
174a0 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
174b0 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
174c0 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
174d0 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
174e0 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
174f0 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
17500 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
17510 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
17520 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
17530 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
17540 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
17550 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
17560 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
17570 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
17580 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
17590 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
175a0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
175b0 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
175c0 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
175d0 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
175e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
175f0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
17600 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
17610 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
17620 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
17630 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
17640 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
17650 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
17660 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
17670 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
17680 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
17690 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
176a0 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
176b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
176c0 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
176d0 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
176e0 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
176f0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
17700 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
17710 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
17720 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
17730 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
17740 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
17750 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
17760 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
17770 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
17780 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
17790 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
177a0 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
177b0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
177c0 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
177d0 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
177e0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
177f0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
17800 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
17810 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
17820 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
17830 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
17840 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
17850 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
17860 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
17870 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
17880 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
17890 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
178a0 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
178b0 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
178c0 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
178d0 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
178e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
178f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
17900 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
17910 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
17920 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
17930 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
17940 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
17950 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
17960 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
17970 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
17980 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
17990 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
179a0 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
179b0 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
179c0 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
179d0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
179e0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
179f0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
17a00 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
17a10 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
17a20 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
17a30 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
17a40 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
17a50 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
17a60 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
17a70 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
17a80 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
17a90 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
17aa0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
17ab0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
17ac0 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
17ad0 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
17ae0 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
17af0 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
17b00 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
17b10 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
17b20 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
17b30 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
17b40 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
17b50 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
17b60 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
17b70 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
17b80 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
17b90 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
17ba0 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
17bb0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
17bc0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
17bd0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
17be0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
17bf0 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
17c00 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
17c10 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
17c20 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
17c30 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
17c40 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
17c50 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64  TS3_TOKENIZER</d
17c60 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
17c70 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
17c80 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
17c90 61 62 6c 65 20 74 68 65 20 74 77 6f 2d 61 72 67  able the two-arg
17ca0 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e  ument.** version
17cb0 20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f 74 6f   of the [fts3_to
17cc0 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63 74  kenizer()] funct
17cd0 69 6f 6e 20 77 68 69 63 68 20 69 73 20 70 61 72  ion which is par
17ce0 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53  t of the.** [FTS
17cf0 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61  3] full-text sea
17d00 72 63 68 20 65 6e 67 69 6e 65 20 65 78 74 65 6e  rch engine exten
17d10 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73  sion..** There s
17d20 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
17d30 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
17d40 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
17d50 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
17d60 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
17d70 30 20 74 6f 20 64 69 73 61 62 6c 65 20 66 74 73  0 to disable fts
17d80 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72  3_tokenizer() or
17d90 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
17da0 65 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65  enable fts3_toke
17db0 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65 67 61 74  nizer() or negat
17dc0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
17dd0 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68   setting.** unch
17de0 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
17df0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
17e00 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
17e10 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
17e20 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
17e30 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
17e40 69 63 61 74 65 20 77 68 65 74 68 65 72 20 66 74  icate whether ft
17e50 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20  s3_tokenizer is 
17e60 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
17e70 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
17e80 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
17e90 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17ea0 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
17eb0 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
17ec0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65  hich case the ne
17ed0 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  w setting is not
17ee0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
17ef0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
17f00 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17f10 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45  ENABLE_LOAD_EXTE
17f20 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  NSION</dt>.** <d
17f30 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
17f40 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
17f50 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
17f60 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
17f70 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69  xtension()].** i
17f80 6e 74 65 72 66 61 63 65 20 69 6e 64 65 70 65 6e  nterface indepen
17f90 64 65 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c  dently of the [l
17fa0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
17fb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
17fc0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  * The [sqlite3_e
17fd0 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
17fe0 73 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61 62  sion()] API enab
17ff0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
18000 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50  both the.** C-AP
18010 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  I [sqlite3_load_
18020 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64  extension()] and
18030 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
18040 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  n [load_extensio
18050 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  n()]..** There s
18060 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
18070 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
18080 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 66  s..** When the f
18090 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
180a0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
180b0 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20  is 1, then only 
180c0 74 68 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20  the C-API is.** 
180d0 65 6e 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20  enabled and the 
180e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d  SQL function rem
180f0 61 69 6e 73 20 64 69 73 61 62 6c 65 64 2e 20 20  ains disabled.  
18100 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67  If the first arg
18110 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73  ument to.** this
18120 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 30 2c   interface is 0,
18130 20 74 68 65 6e 20 62 6f 74 68 20 74 68 65 20 43   then both the C
18140 2d 41 50 49 20 61 6e 64 20 74 68 65 20 53 51 4c  -API and the SQL
18150 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 64 69   function are di
18160 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68  sabled..** If th
18170 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18180 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20   is -1, then no 
18190 63 68 61 6e 67 65 73 20 61 72 65 20 6d 61 64 65  changes are made
181a0 20 74 6f 20 73 74 61 74 65 20 6f 66 20 65 69 74   to state of eit
181b0 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49  her the.** C-API
181c0 20 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63   or the SQL func
181d0 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63  tion..** The sec
181e0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
181f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
18200 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
18210 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
18220 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
18230 63 61 74 65 20 77 68 65 74 68 65 72 20 5b 73 71  cate whether [sq
18240 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
18250 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63  sion()] interfac
18260 65 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c 65 64  e.** is disabled
18270 20 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c   or enabled foll
18280 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
18290 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
182a0 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65  ameter may.** be
182b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
182c0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
182d0 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69  he new setting i
182e0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
182f0 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ack..** </dd>.**
18300 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
18310 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41  BCONFIG_MAINDBNA
18320 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ME</dt>.** <dd> 
18330 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
18340 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
18350 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 22  he name of the "
18360 6d 61 69 6e 22 20 64 61 74 61 62 61 73 65 0a 2a  main" database.*
18370 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54 68 65 20  * schema.  ^The 
18380 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74 20 69 73  sole argument is
18390 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
183a0 63 6f 6e 73 74 61 6e 74 20 55 54 46 38 20 73 74  constant UTF8 st
183b0 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68 20 77 69  ring.** which wi
183c0 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 6e 65  ll become the ne
183d0 77 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e  w schema name in
183e0 20 70 6c 61 63 65 20 6f 66 20 22 6d 61 69 6e 22   place of "main"
183f0 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f  .  ^SQLite.** do
18400 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f  es not make a co
18410 70 79 20 6f 66 20 74 68 65 20 6e 65 77 20 6d 61  py of the new ma
18420 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 73  in schema name s
18430 74 72 69 6e 67 2c 20 73 6f 20 74 68 65 20 61 70  tring, so the ap
18440 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
18450 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
18460 65 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  e argument passe
18470 64 20 69 6e 74 6f 20 74 68 69 73 20 44 42 43 4f  d into this DBCO
18480 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69 73 20 75  NFIG option is u
18490 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69  nchanged.** unti
184a0 6c 20 61 66 74 65 72 20 74 68 65 20 64 61 74 61  l after the data
184b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
184c0 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  closes..** </dd>
184d0 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
184e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
184f0 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41  BCONFIG_MAINDBNA
18500 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 31 30  ME            10
18510 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68 61 72  00 /* const char
18520 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18530 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
18540 4b 41 53 49 44 45 20 20 20 20 20 20 20 20 20 20  KASIDE          
18550 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a     1001 /* void*
18560 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
18570 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
18580 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
18590 20 20 20 20 20 20 20 20 20 20 31 30 30 32 20 2f            1002 /
185a0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
185b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
185c0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
185d0 47 47 45 52 20 20 20 20 20 20 20 20 31 30 30 33  GGER        1003
185e0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
185f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18600 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
18610 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30  TS3_TOKENIZER 10
18620 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  04 /* int int* *
18630 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18640 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
18650 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20  _LOAD_EXTENSION 
18660 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1005 /* int int*
18670 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   */.../*.** CAPI
18680 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
18690 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64  Disable Extended
186a0 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
186b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
186c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
186d0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
186e0 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
186f0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
18700 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
18710 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
18720 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
18730 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65  f SQLite. ^The e
18740 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
18750 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
18760 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
18770 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
18780 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
18790 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
187a0 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
187b0 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
187c0 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
187d0 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
187e0 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d  nsert Rowid.** M
187f0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
18800 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79  *.** ^Each entry
18810 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20   in most SQLite 
18820 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66  tables (except f
18830 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  or [WITHOUT ROWI
18840 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61  D] tables).** ha
18850 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
18860 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
18870 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
18880 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
18890 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64  id"]. ^The rowid
188a0 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
188b0 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
188c0 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
188d0 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
188e0 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
188f0 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
18900 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
18910 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
18920 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
18930 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20  columns. ^If.** 
18940 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
18950 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b  column of type [
18960 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
18970 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63  KEY] then that c
18980 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
18990 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
189a0 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e  e rowid..**.** ^
189b0 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  The sqlite3_last
189c0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
189d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
189e0 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
189f0 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72  f the .** most r
18a00 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c  ecent successful
18a10 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61   [INSERT] into a
18a20 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20   rowid table or 
18a30 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
18a40 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63  ** on database c
18a50 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20  onnection D..** 
18a60 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57  ^Inserts into [W
18a70 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
18a80 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63  bles are not rec
18a90 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f  orded..** ^If no
18aa0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
18ab0 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64  ERT]s into rowid
18ac0 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20   tables.** have 
18ad0 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
18ae0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
18af0 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20  nnection D, .** 
18b00 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73  then sqlite3_las
18b10 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
18b20 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
18b30 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
18b40 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
18b50 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f  thin a trigger o
18b60 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74  r within a [virt
18b70 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65  ual table].** me
18b80 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20  thod, then this 
18b90 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74  routine will ret
18ba0 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  urn the [rowid] 
18bb0 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
18bc0 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ** row as long a
18bd0 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  s the trigger or
18be0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
18bf0 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67  ethod is running
18c00 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
18c10 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
18c20 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
18c30 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75  d ends, the valu
18c40 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62  e returned .** b
18c50 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  y this routine r
18c60 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69  everts to what i
18c70 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65  t was before the
18c80 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
18c90 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74  ual.** table met
18ca0 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a  hod began.)^.**.
18cb0 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
18cc0 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
18cd0 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
18ce0 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
18cf0 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
18d00 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
18d10 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
18d20 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
18d30 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
18d40 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
18d50 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
18d60 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
18d70 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
18d80 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
18d90 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
18da0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
18db0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
18dc0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
18dd0 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
18de0 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
18df0 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
18e00 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
18e10 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
18e20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
18e30 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
18e40 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
18e50 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
18e60 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
18e70 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
18e80 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
18e90 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
18ea0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
18eb0 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
18ec0 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
18ed0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
18ee0 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
18ef0 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
18f00 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
18f10 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
18f20 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
18f30 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
18f40 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
18f50 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
18f60 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
18f70 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
18f80 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
18f90 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
18fa0 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
18fb0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
18fc0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
18fd0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
18fe0 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
18ff0 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
19000 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
19010 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
19020 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
19030 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
19040 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
19050 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
19060 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
19070 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
19080 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
19090 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
190a0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
190b0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
190c0 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
190d0 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
190e0 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
190f0 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
19100 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
19110 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
19120 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
19130 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
19140 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19150 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
19160 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
19170 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
19180 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
19190 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
191a0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  3.**.** ^This fu
191b0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
191c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
191d0 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65  s modified, inse
191e0 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  rted or.** delet
191f0 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
19200 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
19210 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
19220 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
19230 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64  atement on the d
19240 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19250 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20  on specified by 
19260 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
19270 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e  er..** ^Executin
19280 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65  g any other type
19290 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
192a0 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66  t does not modif
192b0 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  y the value.** r
192c0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
192d0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
192e0 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61  ^Only changes ma
192f0 64 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74  de directly by t
19300 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  he INSERT, UPDAT
19310 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
19320 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e  ement are.** con
19330 73 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69  sidered - auxili
19340 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
19350 65 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52  ed by [CREATE TR
19360 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
19370 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20  ], .** [foreign 
19380 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20  key actions] or 
19390 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
193a0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  aint resolution 
193b0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
193c0 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20  .** .** Changes 
193d0 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
193e0 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
193f0 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f  y .** [INSTEAD O
19400 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54  F trigger | INST
19410 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d  EAD OF triggers]
19420 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
19430 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a  . ^The value .**
19440 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
19450 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
19460 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72  mmediately after
19470 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
19480 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45  TE or .** DELETE
19490 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f   statement run o
194a0 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61  n a view is alwa
194b0 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68  ys zero. Only ch
194c0 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65  anges made to re
194d0 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72  al .** tables ar
194e0 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
194f0 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65   Things are more
19500 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20   complicated if 
19510 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
19520 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ges() function i
19530 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68  s.** executed wh
19540 69 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72  ile a trigger pr
19550 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67  ogram is running
19560 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65  . This may happe
19570 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67  n if the.** prog
19580 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68  ram uses the [ch
19590 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
195a0 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d  tion], or if som
195b0 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b  e other callback
195c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76  .** function inv
195d0 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61  okes sqlite3_cha
195e0 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e  nges() directly.
195f0 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a   Essentially:.**
19600 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c   .** <ul>.**   <
19610 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74  li> ^(Before ent
19620 65 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20  ering a trigger 
19630 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75  program the valu
19640 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  e returned by.**
19650 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
19660 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
19670 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74  on is saved. Aft
19680 65 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70  er the trigger p
19690 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20  rogram .**      
196a0 20 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20    has finished, 
196b0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c  the original val
196c0 75 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29  ue is restored.)
196d0 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ^.** .**   <li> 
196e0 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67  ^(Within a trigg
196f0 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20  er program each 
19700 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61  INSERT, UPDATE a
19710 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20  nd DELETE .**   
19720 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73       statement s
19730 65 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65  ets the value re
19740 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
19750 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
19760 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70         upon comp
19770 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c  letion as normal
19780 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69  . Of course, thi
19790 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74  s value will not
197a0 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20   include .**    
197b0 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20      any changes 
197c0 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62  performed by sub
197d0 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68  -triggers, as th
197e0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
197f0 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76  s() .**        v
19800 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76  alue will be sav
19810 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20  ed and restored 
19820 61 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74  after each sub-t
19830 72 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29  rigger has run.)
19840 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a  ^.** </ul>.** .*
19850 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68  * ^This means th
19860 61 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65  at if the change
19870 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
19880 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73   (or similar) is
19890 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20   used.** by the 
198a0 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50  first INSERT, UP
198b0 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
198c0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
198d0 61 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a  a trigger, it .*
198e0 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  * returns the va
198f0 6c 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20  lue as set when 
19900 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74  the calling stat
19910 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63  ement began exec
19920 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74  uting..** ^If it
19930 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
19940 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71  second or subseq
19950 75 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d  uent such statem
19960 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
19970 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d  gger .** program
19980 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
19990 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68  rned reflects th
199a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
199b0 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65   modified by the
199c0 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e   .** previous IN
199d0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
199e0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
199f0 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
19a00 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   trigger..**.** 
19a10 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
19a20 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
19a30 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
19a40 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
19a50 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
19a60 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65   and the [change
19a70 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
19a80 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
19a90 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
19aa0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
19ab0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
19ac0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
19ad0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
19ae0 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
19af0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
19b00 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  ue returned.** i
19b10 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
19b20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
19b30 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
19b40 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
19b50 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
19b60 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
19b70 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
19b80 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  fied.** METHOD: 
19b90 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
19ba0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
19bb0 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e  urns the total n
19bc0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e  umber of rows in
19bd0 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64  serted, modified
19be0 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62   or.** deleted b
19bf0 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20  y all [INSERT], 
19c00 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c  [UPDATE] or [DEL
19c10 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ETE] statements 
19c20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e  completed.** sin
19c30 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ce the database 
19c40 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f  connection was o
19c50 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67  pened, including
19c60 20 74 68 6f 73 65 20 65 78 65 63 75 74 65 64 20   those executed 
19c70 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72  as.** part of tr
19c80 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20  igger programs. 
19c90 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
19ca0 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
19cb0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f   statement.** do
19cc0 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68  es not affect th
19cd0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
19ce0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61   by sqlite3_tota
19cf0 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20  l_changes()..** 
19d00 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64  .** ^Changes mad
19d10 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f  e as part of [fo
19d20 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
19d30 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20  s] are included 
19d40 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c  in the.** count,
19d50 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20   but those made 
19d60 61 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41  as part of REPLA
19d70 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  CE constraint re
19d80 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20  solution are.** 
19d90 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f  not. ^Changes to
19da0 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
19db0 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
19dc0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
19dd0 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ers .** are not 
19de0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  counted..** .** 
19df0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
19e00 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
19e10 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
19e20 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
19e30 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
19e40 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65  he [total_change
19e50 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
19e60 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
19e70 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
19e80 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
19e90 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
19ea0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
19eb0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
19ec0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
19ed0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
19ee0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
19ef0 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
19f00 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
19f10 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
19f20 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
19f30 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
19f40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19f50 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
19f60 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
19f70 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  y.** METHOD: sql
19f80 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
19f90 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
19fa0 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
19fb0 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
19fc0 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
19fd0 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
19fe0 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
19ff0 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
1a000 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
1a010 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
1a020 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
1a030 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
1a040 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
1a050 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
1a060 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
1a070 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
1a080 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
1a090 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
1a0a0 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
1a0b0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1a0c0 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
1a0d0 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
1a0e0 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
1a0f0 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
1a100 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
1a110 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
1a120 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
1a130 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
1a140 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1a150 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
1a160 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
1a170 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
1a180 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
1a190 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
1a1a0 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
1a1b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
1a1c0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1a1d0 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
1a1e0 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
1a1f0 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
1a200 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
1a210 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
1a220 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
1a230 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
1a240 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
1a250 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
1a260 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
1a270 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
1a280 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
1a290 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
1a2a0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
1a2b0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
1a2c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
1a2d0 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
1a2e0 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
1a2f0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
1a300 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
1a310 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
1a320 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
1a330 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
1a340 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
1a350 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
1a360 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
1a370 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
1a380 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1a390 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
1a3a0 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
1a3b0 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
1a3c0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1a3d0 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
1a3e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
1a3f0 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
1a400 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
1a410 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1a420 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1a430 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1a440 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
1a450 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
1a460 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
1a470 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
1a480 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
1a490 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
1a4a0 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
1a4b0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
1a4c0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
1a4d0 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
1a4e0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1a4f0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1a500 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
1a510 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
1a520 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
1a530 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
1a540 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1a550 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
1a560 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
1a570 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
1a580 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
1a590 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
1a5a0 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
1a5b0 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
1a5c0 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
1a5d0 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
1a5e0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1a5f0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1a600 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1a610 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
1a620 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  s..**.** If the 
1a630 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a640 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65  ion closes while
1a650 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
1a660 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e  upt()].** is run
1a670 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
1a680 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
1a690 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64   happen..*/.void
1a6a0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1a6b0 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  pt(sqlite3*);../
1a6c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
1a6d0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
1a6e0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20  QL Statement Is 
1a6f0 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54  Complete.**.** T
1a700 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1a710 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20  e useful during 
1a720 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
1a730 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
1a740 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
1a750 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
1a760 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61   seems to form a
1a770 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
1a780 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
1a790 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
1a7a0 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
1a7b0 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
1a7c0 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
1a7d0 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
1a7e0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1a7f0 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65   return 1 if the
1a800 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
1a810 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
1a820 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
1a830 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61  atement.  ^A sta
1a840 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
1a850 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
1a860 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
1a870 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  th a semicolon t
1a880 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20  oken and is not 
1a890 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a  a prefix of a.**
1a8a0 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45   well-formed CRE
1a8b0 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
1a8c0 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c  ement.  ^Semicol
1a8d0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62  ons that are emb
1a8e0 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  edded within.** 
1a8f0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20  string literals 
1a900 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69  or quoted identi
1a910 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f  fier names or co
1a920 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a  mments are not.*
1a930 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f  * independent to
1a940 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70  kens (they are p
1a950 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e  art of the token
1a960 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61   in which they a
1a970 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20  re.** embedded) 
1a980 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20  and thus do not 
1a990 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65  count as a state
1a9a0 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e  ment terminator.
1a9b0 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a    ^Whitespace.**
1a9c0 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68   and comments th
1a9d0 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69  at follow the fi
1a9e0 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72  nal semicolon ar
1a9f0 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  e ignored..**.**
1aa00 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1aa10 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65   return 0 if the
1aa20 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e   statement is in
1aa30 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61  complete.  ^If a
1aa40 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
1aa50 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65  ation fails, the
1aa60 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69  n SQLITE_NOMEM i
1aa70 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1aa80 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1aa90 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
1aaa0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1aab0 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
1aac0 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
1aad0 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
1aae0 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  t SQL..**.** ^(I
1aaf0 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74  f SQLite has not
1ab00 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65   been initialize
1ab10 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1ab20 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70  _initialize()] p
1ab30 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f  rior .** to invo
1ab40 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d  king sqlite3_com
1ab50 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73  plete16() then s
1ab60 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
1ab70 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
1ab80 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
1ab90 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  by sqlite3_compl
1aba0 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61  ete16().  If tha
1abb0 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  t initialization
1abc0 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20   fails,.** then 
1abd0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1abe0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
1abf0 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20  mplete16() will 
1ac00 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72  be non-zero.** r
1ac10 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1ac20 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
1ac30 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d  input SQL is com
1ac40 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  plete.)^.**.** T
1ac50 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
1ac60 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
1ac70 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
1ac80 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
1ac90 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
1aca0 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1acb0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1acc0 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  16()] must be a 
1acd0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1ace0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
1acf0 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
1ad00 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  order..*/.int sq
1ad10 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
1ad20 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
1ad30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
1ad40 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
1ad50 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
1ad60 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
1ad70 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
1ad80 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
1ad90 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b  BUSY Errors.** K
1ada0 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68  EYWORDS: {busy-h
1adb0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d  andler callback}
1adc0 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a   {busy handler}.
1add0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1ade0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
1adf0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1ae00 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e  er(D,X,P) routin
1ae10 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
1ae20 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20  k function X.** 
1ae30 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
1ae40 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
1ae50 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
1ae60 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
1ae70 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61  made to access a
1ae80 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
1ae90 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
1aea0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1aeb0 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20  nection] D when 
1aec0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
1aed0 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
1aee0 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65   the table locke
1aef0 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
1af00 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1af10 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
1af20 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a  ed to implement.
1af30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
1af40 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20  _timeout()] and 
1af50 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1af60 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  eout]..**.** ^If
1af70 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
1af80 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
1af90 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1afa0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
1afb0 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
1afc0 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
1afd0 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
1afe0 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
1aff0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
1b000 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
1b010 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1b020 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
1b030 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
1b040 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1b050 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1b060 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
1b070 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
1b080 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
1b090 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1b0a0 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
1b0b0 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
1b0c0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1b0d0 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
1b0e0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1b0f0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
1b100 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
1b110 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
1b120 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
1b130 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72  d previously for
1b140 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e   the same lockin
1b150 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
1b160 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
1b170 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
1b180 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
1b190 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
1b1a0 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
1b1b0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
1b1c0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69   [SQLITE_BUSY] i
1b1d0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f  s returned.** to
1b1e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1b1f0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
1b200 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
1b210 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
1b220 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
1b230 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1b240 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
1b250 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
1b260 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
1b270 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
1b280 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
1b290 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
1b2a0 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
1b2b0 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
1b2c0 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
1b2d0 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
1b2e0 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
1b2f0 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
1b300 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
1b310 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
1b320 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
1b330 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
1b340 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1b350 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  BUSY].** to the 
1b360 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74  application inst
1b370 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
1b380 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e  the .** busy han
1b390 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
1b3a0 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
1b3b0 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
1b3c0 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
1b3d0 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
1b3e0 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
1b3f0 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
1b400 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
1b410 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
1b420 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1b430 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
1b440 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
1b450 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1b460 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
1b470 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
1b480 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
1b490 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
1b4a0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1b4b0 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
1b4c0 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
1b4d0 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
1b4e0 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
1b4f0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1b500 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
1b510 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
1b520 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
1b530 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
1b540 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
1b550 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
1b560 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
1b570 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
1b580 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
1b590 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
1b5a0 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
1b5b0 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
1b5c0 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
1b5d0 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
1b5e0 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
1b5f0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
1b600 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
1b610 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
1b620 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
1b630 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
1b640 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1b650 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1b660 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
1b670 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
1b680 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1b690 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
1b6a0 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
1b6b0 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
1b6c0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1b6d0 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
1b6e0 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
1b6f0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1b700 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76  eout()].** or ev
1b710 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41  aluating [PRAGMA
1b720 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d   busy_timeout=N]
1b730 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65   will change the
1b740 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
1b750 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20   and thus clear 
1b760 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73  any previously s
1b770 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  et busy handler.
1b780 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
1b790 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
1b7a0 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
1b7b0 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
1b7c0 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
1b7d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1b7e0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1b7f0 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20  sy handler.  In 
1b800 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20  other words,.** 
1b810 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1b820 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
1b830 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  t.  Any such act
1b840 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
1b850 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
1b860 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
1b870 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
1b880 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
1b890 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b8a0 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
1b8b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
1b8c0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1b8d0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
1b8e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1b8f0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
1b900 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  *,int(*)(void*,i
1b910 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  nt),void*);../*.
1b920 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
1b930 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
1b940 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1b950 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  e3.**.** ^This r
1b960 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
1b970 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1b980 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
1b990 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
1b9a0 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
1b9b0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
1b9c0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
1b9d0 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
1b9e0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
1b9f0 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
1ba00 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
1ba10 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
1ba20 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
1ba30 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
1ba40 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
1ba50 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1ba60 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1ba70 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
1ba80 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
1ba90 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
1baa0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
1bab0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
1bac0 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_BUSY]..**.** 
1bad0 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
1bae0 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
1baf0 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
1bb00 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
1bb10 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
1bb20 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
1bb30 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1bb40 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1bb50 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1bb60 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
1bb70 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1bb80 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61  connection] at a
1bb90 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
1bba0 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
1bbb0 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
1bbc0 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
1bbd0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1bbe0 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
1bbf0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
1bc00 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
1bc10 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
1bc20 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
1bc30 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
1bc40 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79  o:  [PRAGMA busy
1bc50 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74  _timeout].*/.int
1bc60 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
1bc70 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
1bc80 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
1bc90 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
1bca0 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
1bcb0 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
1bcc0 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
1bcd0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73  lite3.**.** This
1bce0 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
1bcf0 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
1bd00 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
1bd10 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1bd20 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
1bd30 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
1bd40 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
1bd50 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
1bd60 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
1bd70 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
1bd80 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
1bd90 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
1bda0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
1bdb0 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
1bdc0 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
1bdd0 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
1bde0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
1bdf0 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
1be00 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
1be10 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
1be20 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
1be30 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
1be40 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
1be50 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
1be60 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
1be70 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
1be80 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
1be90 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
1bea0 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
1beb0 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
1bec0 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
1bed0 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
1bee0 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
1bef0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
1bf00 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1bf10 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
1bf20 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
1bf30 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1bf40 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
1bf50 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
1bf60 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
1bf70 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
1bf80 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
1bf90 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
1bfa0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1bfb0 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
1bfc0 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
1bfd0 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
1bfe0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
1bff0 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
1c000 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
1c010 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
1c020 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
1c030 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
1c040 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
1c050 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
1c060 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1c070 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
1c080 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
1c090 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1c0a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
1c0b0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1c0c0 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
1c0d0 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
1c0e0 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
1c0f0 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
1c100 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
1c110 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1c120 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
1c130 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
1c140 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1c150 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
1c160 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
1c170 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1c180 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
1c190 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
1c1a0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
1c1b0 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
1c1c0 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
1c1d0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1c1e0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1c1f0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1c200 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
1c210 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
1c220 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1c230 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
1c240 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
1c250 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
1c260 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
1c270 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
1c280 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
1c290 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1c2a0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
1c2b0 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
1c2c0 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
1c2d0 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
1c2e0 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
1c2f0 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
1c300 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
1c310 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
1c320 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
1c330 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
1c340 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
1c350 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
1c360 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
1c370 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1c380 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1c390 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
1c3a0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1c3b0 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
1c3c0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1c3d0 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
1c3e0 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
1c3f0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1c400 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
1c410 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1c420 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
1c430 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1c440 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
1c450 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1c460 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
1c470 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
1c480 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
1c490 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
1c4a0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1c4b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c4c0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
1c4d0 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
1c4e0 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
1c4f0 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
1c500 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
1c510 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
1c520 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1c530 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
1c540 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
1c550 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
1c560 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
1c570 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
1c580 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
1c590 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
1c5a0 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
1c5b0 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
1c5c0 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
1c5d0 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
1c5e0 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
1c5f0 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
1c600 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
1c610 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
1c620 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
1c630 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
1c640 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
1c650 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
1c660 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
1c670 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
1c680 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1c690 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
1c6a0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1c6b0 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
1c6c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
1c6d0 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
1c6e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1c6f0 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
1c700 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
1c710 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
1c720 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
1c730 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
1c740 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
1c750 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1c760 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
1c770 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
1c780 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
1c790 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
1c7a0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
1c7b0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1c7c0 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
1c7d0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
1c7e0 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
1c7f0 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
1c800 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
1c810 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
1c820 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
1c830 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
1c840 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
1c850 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
1c860 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
1c870 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
1c880 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
1c890 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
1c8a0 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
1c8b0 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
1c8c0 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
1c8d0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
1c8e0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1c8f0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1c900 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69  _errmsg()]..*/.i
1c910 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
1c920 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
1c930 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
1c940 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
1c950 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1c960 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
1c970 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
1c980 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
1c990 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
1c9a0 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
1c9b0 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
1c9c0 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
1c9d0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1c9e0 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
1c9f0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
1ca00 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
1ca10 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1ca20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
1ca30 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1ca40 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
1ca50 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
1ca60 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
1ca70 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
1ca80 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
1ca90 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
1caa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1cab0 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
1cac0 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
1cad0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1cae0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
1caf0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
1cb00 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
1cb10 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
1cb20 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
1cb30 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
1cb40 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1cb50 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74   understand most
1cb60 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b   of the common K
1cb70 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  &R formatting op
1cb80 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73  tions,.** plus s
1cb90 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e  ome additional n
1cba0 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d  on-standard form
1cbb0 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65  ats, detailed be
1cbc0 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  low..** Note tha
1cbd0 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f  t some of the mo
1cbe0 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61  re obscure forma
1cbf0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72  tting options fr
1cc00 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c  om recent.** C-l
1cc10 69 62 72 61 72 79 20 73 74 61 6e 64 61 72 64 73  ibrary standards
1cc20 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f   are omitted fro
1cc30 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74  m this implement
1cc40 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
1cc50 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
1cc60 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
1cc70 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
1cc80 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
1cc90 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
1cca0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
1ccb0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
1ccc0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
1ccd0 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
1cce0 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
1ccf0 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
1cd00 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
1cd10 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1cd20 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
1cd30 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
1cd40 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
1cd50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1cd60 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1cd70 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
1cd80 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1cd90 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
1cda0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
1cdb0 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
1cdc0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1cdd0 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
1cde0 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
1cdf0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1ce00 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
1ce10 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
1ce20 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
1ce30 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
1ce40 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1ce50 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
1ce60 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
1ce70 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1ce80 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1ce90 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
1cea0 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
1ceb0 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
1cec0 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
1ced0 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
1cee0 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
1cef0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
1cf00 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
1cf10 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
1cf20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1cf30 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
1cf40 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
1cf50 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1cf60 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1cf70 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
1cf80 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1cf90 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
1cfa0 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
1cfb0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1cfc0 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
1cfd0 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
1cfe0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
1cff0 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
1d000 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
1d010 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
1d020 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
1d030 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
1d040 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1d050 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1d060 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
1d070 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
1d080 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
1d090 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
1d0a0 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
1d0b0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
1d0c0 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
1d0d0 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
1d0e0 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
1d0f0 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
1d100 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
1d110 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
1d120 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
1d130 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
1d140 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
1d150 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
1d160 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
1d170 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
1d180 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
1d190 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
1d1a0 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
1d1b0 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
1d1c0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
1d1d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
1d1e0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1d1f0 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
1d200 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
1d210 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
1d220 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1d230 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
1d240 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1d250 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
1d260 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
1d270 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
1d280 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
1d290 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
1d2a0 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
1d2b0 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
1d2c0 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
1d2d0 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
1d2e0 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
1d2f0 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64  , "%Q", "%w" and
1d300 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
1d310 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70  *.** ^(The %q op
1d320 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1d330 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
1d340 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d  bstitutes a nul-
1d350 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
1d360 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
1d370 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
1d380 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
1d390 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
1d3a0 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
1d3b0 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
1d3c0 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
1d3d0 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79  g literal.)^  By
1d3e0 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
1d3f0 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
1d400 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
1d410 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
1d420 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
1d430 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
1d440 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
1d450 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61  * For example, a
1d460 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67  ssume the string
1d470 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20   variable zText 
1d480 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
1d490 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1d4a0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1d4b0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
1d4c0 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
1d4d0 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
1d4e0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1d4f0 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
1d500 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
1d510 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1d520 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1d530 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1d540 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1d550 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1d560 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1d570 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
1d580 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
1d590 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1d5a0 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1d5b0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1d5c0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1d5d0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1d5e0 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
1d5f0 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
1d600 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
1d610 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
1d620 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
1d630 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
1d640 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
1d650 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1d660 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1d670 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1d680 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1d690 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
1d6a0 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
1d6b0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1d6c0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
1d6d0 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
1d6e0 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
1d6f0 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
1d700 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
1d710 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
1d720 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
1d730 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1d740 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1d750 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1d760 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1d770 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
1d780 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1d790 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
1d7a0 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
1d7b0 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
1d7c0 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
1d7d0 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61   you should.** a
1d7e0 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
1d7f0 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
1d800 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
1d810 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74  nto a string lit
1d820 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  eral..**.** ^(Th
1d830 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
1d840 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
1d850 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
1d860 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
1d870 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
1d880 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
1d890 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  tring.  Addition
1d8a0 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72  ally, if the par
1d8b0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a  ameter in the.**
1d8c0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69   argument list i
1d8d0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1d8e0 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73  , %Q substitutes
1d8f0 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22   the text "NULL"
1d900 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e   (without.** sin
1d910 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20  gle quotes).)^  
1d920 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  So, for example,
1d930 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a   one could say:.
1d940 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1d950 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1d960 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1d970 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1d980 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1d990 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b  ES(%Q)", zText);
1d9a0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1d9b0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1d9c0 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1d9d0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1d9e0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1d9f0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ote>.**.** The c
1da00 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72  ode above will r
1da10 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20  ender a correct 
1da20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1da30 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72   the zSQL.** var
1da40 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68  iable even if th
1da50 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65  e zText variable
1da60 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1da70 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  er..**.** ^(The 
1da80 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%w" formatting 
1da90 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22  option is like "
1daa0 25 71 22 20 65 78 63 65 70 74 20 74 68 61 74 20  %q" except that 
1dab0 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a  it expects to.**
1dac0 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69   be contained wi
1dad0 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74  thin double-quot
1dae0 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69  es instead of si
1daf0 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64  ngle quotes, and
1db00 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74   it.** escapes t
1db10 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20  he double-quote 
1db20 63 68 61 72 61 63 74 65 72 20 69 6e 73 74 65 61  character instea
1db30 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d  d of the single-
1db40 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74  quote.** charact
1db50 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20  er.)^  The "%w" 
1db60 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1db70 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  n is intended fo
1db80 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69  r safely inserti
1db90 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20  ng.** table and 
1dba0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74  column names int
1dbb0 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20  o a constructed 
1dbc0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
1dbd0 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20  *.** ^(The "%z" 
1dbe0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1dbf0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73  n works like "%s
1dc00 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a  " but with the.*
1dc10 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
1dc20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
1dc30 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
1dc40 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
1dc50 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
1dc60 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
1dc70 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
1dc80 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a  input string.)^.
1dc90 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
1dca0 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
1dcb0 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
1dcc0 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
1dcd0 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
1dce0 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
1dcf0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1dd00 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1dd10 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61  char*, ...);.cha
1dd20 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
1dd30 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1dd40 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1dd50 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
1dd60 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1dd70 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
1dd80 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
1dd90 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
1dda0 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
1ddb0 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
1ddc0 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
1ddd0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
1dde0 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
1ddf0 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
1de00 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
1de10 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
1de20 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
1de30 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
1de40 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
1de50 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
1de60 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
1de70 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1de80 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
1de90 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
1dea0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1deb0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1dec0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1ded0 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
1dee0 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
1def0 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
1df00 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
1df10 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
1df20 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1df30 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
1df40 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
1df50 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
1df60 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
1df70 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
1df80 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
1df90 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
1dfa0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
1dfb0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
1dfc0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1dfd0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
1dfe0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1dff0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1e000 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74  malloc64(N) rout
1e010 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c  ine works just l
1e020 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ike.** sqlite3_m
1e030 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20  alloc(N) except 
1e040 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73  that N is an uns
1e050 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74  igned 64-bit int
1e060 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
1e070 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62  of a signed 32-b
1e080 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  it integer..**.*
1e090 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
1e0a0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
1e0b0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
1e0c0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
1e0d0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1e0e0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1e0f0 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
1e100 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
1e110 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
1e120 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
1e130 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
1e140 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
1e150 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
1e160 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
1e170 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
1e180 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
1e190 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
1e1a0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
1e1b0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
1e1c0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
1e1d0 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
1e1e0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
1e1f0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
1e200 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
1e210 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
1e220 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
1e230 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1e240 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
1e250 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
1e260 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
1e270 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1e280 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
1e290 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
1e2a0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
1e2b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1e2c0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1e2d0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
1e2e0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
1e2f0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1e300 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1e310 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1e320 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  oc()..**.** ^The
1e330 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1e340 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (X,N) interface 
1e350 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
1e360 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
1e370 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1e380 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  X to be at least
1e390 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66   N bytes..** ^If
1e3a0 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72   the X parameter
1e3b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1e3c0 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61  loc(X,N).** is a
1e3d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1e3e0 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
1e3f0 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
1e400 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1e410 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a  e3_malloc(N)..**
1e420 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d   ^If the N param
1e430 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1e440 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20  realloc(X,N) is 
1e450 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
1e460 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
1e470 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
1e480 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
1e490 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1e4a0 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c  free(X)..** ^sql
1e4b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1e4c0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
1e4d0 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
1e4e0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
1e4f0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1e500 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
1e510 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
1e520 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69  t memory is avai
1e530 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
1e540 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
1e550 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1e560 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
1e570 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
1e580 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1e590 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
1e5a0 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
1e5b0 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
1e5c0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1e5d0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1e5e0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
1e5f0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
1e600 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
1e610 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72  3_realloc(X,N) r
1e620 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20  eturns NULL and 
1e630 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  N is positive, t
1e640 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72  hen the.** prior
1e650 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e   allocation is n
1e660 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
1e670 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
1e680 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65  lloc64(X,N) inte
1e690 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65  rfaces works the
1e6a0 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69   same as.** sqli
1e6b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1e6c0 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1e6d0 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67  s a 64-bit unsig
1e6e0 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74  ned integer inst
1e6f0 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62  ead.** of a 32-b
1e700 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
1e710 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69  r..**.** ^If X i
1e720 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  s a memory alloc
1e730 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79  ation previously
1e740 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1e750 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c  qlite3_malloc(),
1e760 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1e770 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f  oc64(), sqlite3_
1e780 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71  realloc(), or sq
1e790 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1e7a0 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  ), then.** sqlit
1e7b0 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
1e7c0 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
1e7d0 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  that memory allo
1e7e0 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e  cation in bytes.
1e7f0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72  .** ^The value r
1e800 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1e810 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68  e3_msize(X) migh
1e820 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  t be larger than
1e830 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f   the number.** o
1e840 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65  f bytes requeste
1e850 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c  d when X was all
1e860 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69  ocated.  ^If X i
1e870 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1e880 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
1e890 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e  _msize(X) return
1e8a0 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f  s zero.  If X po
1e8b0 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e  ints to somethin
1e8c0 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a  g that is not.**
1e8d0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1e8e0 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
1e8f0 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f  ion, or if it po
1e900 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72  ints to a former
1e910 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f  ly.** valid memo
1e920 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68  ry allocation th
1e930 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20  at has now been 
1e940 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20  freed, then the 
1e950 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73  behavior.** of s
1e960 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1e970 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
1e980 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75   possibly harmfu
1e990 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
1e9a0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
1e9b0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1e9c0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1e9d0 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
1e9e0 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64  _malloc64(), and
1e9f0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1ea00 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  64().** is alway
1ea10 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
1ea20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
1ea30 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20  boundary, or to 
1ea40 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e  a.** 4 byte boun
1ea50 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c  dary if the [SQL
1ea60 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e  ITE_4_BYTE_ALIGN
1ea70 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69  ED_MALLOC] compi
1ea80 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
1ea90 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
1eaa0 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
1eab0 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
1eac0 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
1ead0 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
1eae0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
1eaf0 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
1eb00 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
1eb10 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
1eb20 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
1eb30 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
1eb40 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
1eb50 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
1eb60 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
1eb70 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
1eb80 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
1eb90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
1eba0 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
1ebb0 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
1ebc0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
1ebd0 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20  10, the Windows 
1ebe0 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
1ebf0 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65  er called.** the
1ec00 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
1ec10 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
1ec20 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
1ec30 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
1ec40 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
1ec50 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
1ec60 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
1ec70 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
1ec80 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
1ec90 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
1eca0 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
1ecb0 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
1ecc0 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
1ecd0 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20  ion errors were 
1ece0 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
1ecf0 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72   they were repor
1ed00 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
1ed10 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
1ed20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
1ed30 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
1ed40 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
1ed50 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
1ed60 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
1ed70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
1ed80 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1ed90 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
1eda0 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
1edb0 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
1edc0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
1edd0 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
1ede0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1edf0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
1ee00 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
1ee10 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
1ee20 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
1ee30 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
1ee40 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
1ee50 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
1ee60 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
1ee70 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
1ee80 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
1ee90 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
1eea0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
1eeb0 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
1eec0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
1eed0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
1eee0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
1eef0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1ef00 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74  c64(sqlite3_uint
1ef10 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  64);.void *sqlit
1ef20 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
1ef30 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  , int);.void *sq
1ef40 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1ef50 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
1ef60 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
1ef70 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
1ef80 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  ;.sqlite3_uint64
1ef90 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76   sqlite3_msize(v
1efa0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1efb0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1efc0 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
1efd0 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
1efe0 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
1eff0 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
1f000 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
1f010 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
1f020 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
1f030 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
1f040 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
1f050 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f060 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
1f070 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
1f080 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1f090 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
1f0a0 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
1f0b0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1f0c0 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
1f0d0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1f0e0 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
1f0f0 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
1f100 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
1f110 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
1f120 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
1f130 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1f140 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
1f150 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1f160 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
1f170 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
1f180 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
1f190 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
1f1a0 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
1f1b0 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
1f1c0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
1f1d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1f1e0 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
1f1f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1f200 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1f210 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
1f220 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
1f230 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
1f240 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1f250 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1f260 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
1f270 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
1f280 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
1f290 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
1f2a0 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
1f2b0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
1f2c0 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
1f2d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1f2e0 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
1f2f0 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
1f300 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
1f310 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
1f320 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1f330 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
1f340 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
1f350 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1f360 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1f370 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
1f380 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
1f390 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1f3a0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
1f3b0 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
1f3c0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
1f3d0 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
1f3e0 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
1f3f0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1f400 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
1f410 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1f420 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1f430 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
1f440 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f450 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
1f460 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
1f470 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
1f480 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
1f490 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
1f4a0 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
1f4b0 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
1f4c0 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
1f4d0 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
1f4e0 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
1f4f0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
1f500 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
1f510 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
1f520 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
1f530 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
1f540 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
1f550 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
1f560 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
1f570 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
1f580 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
1f590 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
1f5a0 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
1f5b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
1f5c0 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
1f5d0 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
1f5e0 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
1f5f0 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
1f600 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
1f610 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
1f620 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
1f630 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61   P..** ^The P pa
1f640 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61  rameter can be a
1f650 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1f660 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f  *.** ^If this ro
1f670 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65  utine has not be
1f680 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61  en previously ca
1f690 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70  lled or if the p
1f6a0 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20  revious.** call 
1f6b0 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20  had N less than 
1f6c0 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  one or a NULL po
1f6d0 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65  inter for P, the
1f6e0 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a  n the PRNG is.**
1f6f0 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
1f700 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
1f710 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  d from the xRand
1f720 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
1f730 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
1f740 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1f750 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ject..** ^If the
1f760 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
1f770 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  o this routine h
1f780 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20  ad an N of 1 or 
1f790 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f  more and a.** no
1f7a0 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68  n-NULL P then th
1f7b0 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
1f7c0 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
1f7d0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
1f7e0 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
1f7f0 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
1f800 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
1f810 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
1f820 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1f830 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
1f840 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
1f850 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
1f860 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
1f870 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
1f880 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
1f890 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1f8a0 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
1f8b0 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  rs an authorizer
1f8c0 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
1f8d0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1f8e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f8f0 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
1f900 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
1f910 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75  ment..** ^The au
1f920 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1f930 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
1f940 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
1f950 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
1f960 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1f970 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1f980 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
1f990 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f9a0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1f9b0 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
1f9c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f9d0 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20  e16_v2()].  ^At 
1f9e0 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
1f9f0 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
1fa00 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
1fa10 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
1fa20 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
1fa30 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
1fa40 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
1fa50 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1fa60 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
1fa70 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
1fa80 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
1fa90 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
1faa0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1fab0 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
1fac0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
1fad0 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
1fae0 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
1faf0 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
1fb00 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
1fb10 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
1fb20 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1fb30 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
1fb40 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
1fb50 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1fb60 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
1fb70 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
1fb80 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
1fb90 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
1fba0 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
1fbb0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1fbc0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
1fbd0 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
1fbe0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1fbf0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
1fc00 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
1fc10 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
1fc20 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1fc30 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1fc40 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1fc50 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
1fc60 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1fc70 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1fc80 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
1fc90 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1fca0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1fcb0 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
1fcc0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
1fcd0 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
1fce0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
1fcf0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1fd00 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
1fd10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1fd20 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1fd30 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1fd40 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
1fd50 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
1fd60 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1fd70 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
1fd80 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
1fd90 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
1fda0 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
1fdb0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1fdc0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
1fdd0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
1fde0 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
1fdf0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
1fe00 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
1fe10 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
1fe20 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
1fe30 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
1fe40 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1fe50 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1fe60 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
1fe70 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
1fe80 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
1fe90 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
1fea0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1feb0 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
1fec0 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
1fed0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
1fee0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
1fef0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
1ff00 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
1ff10 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
1ff20 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
1ff30 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
1ff40 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
1ff50 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
1ff60 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1ff70 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
1ff80 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1ff90 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
1ffa0 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
1ffb0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
1ffc0 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
1ffd0 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
1ffe0 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
1fff0 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
20000 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
20010 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
20020 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
20030 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
20040 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
20050 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
20060 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
20070 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
20080 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
20090 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
200a0 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
200b0 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
200c0 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
200d0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
200e0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
200f0 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
20100 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
20110 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
20120 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
20130 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
20140 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
20150 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
20160 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
20170 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
20180 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
20190 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
201a0 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
201b0 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
201c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
201d0 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
201e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
201f0 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
20200 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
20210 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
20220 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
20230 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
20240 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
20250 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
20260 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
20270 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
20280 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
20290 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
202a0 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
202b0 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
202c0 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
202d0 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
202e0 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
202f0 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
20300 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
20310 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
20320 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
20330 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
20340 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
20350 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
20360 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
20370 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
20380 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
20390 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
203a0 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
203b0 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
203c0 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
203d0 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
203e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
203f0 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
20400 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
20410 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
20420 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
20430 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
20440 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
20450 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
20460 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
20470 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
20480 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
20490 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
204a0 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
204b0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
204c0 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
204d0 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
204e0 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
204f0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
20500 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
20510 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
20520 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
20530 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
20540 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
20550 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
20560 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
20570 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
20580 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
20590 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
205a0 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
205b0 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
205c0 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
205d0 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
205e0 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
205f0 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
20600 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
20610 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
20620 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
20630 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
20640 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
20650 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
20660 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
20670 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
20680 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
20690 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
206a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
206b0 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
206c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
206d0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
206e0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
206f0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
20700 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20710 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
20720 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
20730 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
20740 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
20750 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20760 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
20770 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
20780 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
20790 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
207a0 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
207b0 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
207c0 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
207d0 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
207e0 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
207f0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
20800 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
20810 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
20820 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
20830 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
20840 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
20850 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
20860 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
20870 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
20880 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
20890 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
208a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
208b0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
208c0 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
208d0 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
208e0 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
208f0 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
20900 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
20910 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
20920 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
20930 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
20940 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
20950 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
20960 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
20970 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
20980 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
20990 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
209a0 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73  change..*/.int s
209b0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
209c0 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
209d0 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
209e0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
209f0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
20a00 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
20a10 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
20a20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
20a30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20a40 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
20a50 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
20a60 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
20a70 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
20a80 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20a90 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
20aa0 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
20ab0 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
20ac0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
20ad0 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
20ae0 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
20af0 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
20b00 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
20b10 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
20b20 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
20b30 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
20b40 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
20b50 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
20b60 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
20b70 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
20b80 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
20b90 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  t SQLITE_IGNORE 
20ba0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20  is also used as 
20bb0 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f  a [conflict reso
20bc0 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20  lution mode].** 
20bd0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68  returned from th
20be0 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
20bf0 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
20c00 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
20c10 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
20c20 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
20c30 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
20c40 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
20c50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20c60 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
20c70 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
20c80 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
20c90 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
20ca0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
20cb0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
20cc0 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
20cd0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
20ce0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
20cf0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
20d00 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
20d10 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
20d20 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
20d30 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
20d40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
20d50 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
20d60 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
20d70 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
20d80 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
20d90 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
20da0 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
20db0 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
20dc0 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
20dd0 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
20de0 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
20df0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
20e00 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
20e10 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
20e20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
20e30 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
20e40 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
20e50 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
20e60 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
20e70 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
20e80 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
20e90 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
20ea0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
20eb0 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
20ec0 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
20ed0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
20ee0 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
20ef0 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
20f00 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
20f10 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
20f20 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
20f30 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
20f40 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
20f50 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
20f60 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
20f70 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
20f80 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
20f90 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
20fa0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
20fb0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
20fc0 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
20fd0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
20fe0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
20ff0 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
21000 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
21010 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
21020 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
21030 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
21040 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
21050 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
21060 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
21070 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21080 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21090 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
210a0 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
210b0 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
210c0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
210d0 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
210e0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
210f0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
21100 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21110 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
21120 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
21130 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21140 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21150 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21160 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
21170 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
21180 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
21190 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
211a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
211b0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
211c0 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
211d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
211e0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
211f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21200 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
21210 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
21220 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
21230 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21240 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21250 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
21260 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
21270 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
21280 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21290 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
212a0 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
212b0 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
212c0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
212d0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
212e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
212f0 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
21300 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
21310 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
21320 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21340 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
21350 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
21360 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
21370 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21380 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
21390 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
213a0 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
213b0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
213c0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
213d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
213e0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
213f0 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
21400 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
21410 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21420 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21430 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
21440 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
21450 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
21460 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
21470 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
21480 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
21490 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
214a0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
214b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
214c0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
214d0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
214e0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
214f0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
21500 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21510 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
21520 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
21530 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
21540 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21550 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21560 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
21570 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
21580 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
21590 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
215a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
215b0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
215c0 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
215d0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
215e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
215f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21600 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
21610 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
21620 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21630 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21640 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21650 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
21660 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
21670 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
21680 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
21690 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
216a0 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
216b0 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
216c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
216d0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
216e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
216f0 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
21700 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
21710 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21720 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21730 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21740 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
21750 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
21760 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
21770 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21780 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21790 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
217a0 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
217b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
217c0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
217d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
217e0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
217f0 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
21800 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
21810 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21830 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
21840 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
21850 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
21860 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21870 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
21880 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
21890 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
218a0 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
218b0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
218c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
218d0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
218e0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
218f0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
21900 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21910 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
21920 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
21930 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
21940 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
21950 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21960 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
21970 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
21980 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
21990 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
219a0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
219b0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
219c0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
219d0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
219e0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
219f0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
21a00 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
21a10 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
21a20 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
21a30 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
21a40 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
21a50 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
21a60 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
21a70 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
21a80 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
21a90 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
21aa0 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
21ab0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
21ac0 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
21ad0 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
21ae0 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20  LITE_RECURSIVE  
21af0 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f            33   /
21b00 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
21b10 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21b20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    */../*.** CAPI
21b30 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
21b40 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
21b50 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
21b60 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
21b70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
21b80 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 55 73  e deprecated. Us
21b90 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  e the [sqlite3_t
21ba0 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72  race_v2()] inter
21bb0 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20  face.** instead 
21bc0 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20  of the routines 
21bd0 64 65 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a  described here..
21be0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
21bf0 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
21c00 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
21c10 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
21c20 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
21c30 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
21c40 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
21c50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
21c60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
21c70 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
21c80 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
21c90 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
21ca0 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
21cb0 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
21cc0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
21cd0 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
21ce0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21cf0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
21d00 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
21d10 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
21d20 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
21d30 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
21d40 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
21d50 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
21d60 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
21d70 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
21d80 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
21d90 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
21da0 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
21db0 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
21dc0 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
21dd0 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
21de0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
21df0 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
21e00 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
21e10 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
21e20 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
21e30 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ger.)^.**.** The
21e40 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53   [SQLITE_TRACE_S
21e50 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69  IZE_LIMIT] compi
21e60 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63  le-time option c
21e70 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69  an be used to li
21e80 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74  mit.** the lengt
21e90 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61  h of [bound para
21ea0 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e  meter] expansion
21eb0 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f   in the output o
21ec0 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  f sqlite3_trace(
21ed0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )..**.** ^The ca
21ee0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
21ef0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
21f00 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
21f10 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
21f20 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
21f30 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
21f40 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
21f50 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
21f60 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
21f70 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
21f80 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
21f90 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
21fa0 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
21fb0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
21fc0 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65  ok to run.  ^The
21fd0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
21fe0 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20  k.** time is in 
21ff0 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63  units of nanosec
22000 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68  onds, however th
22010 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
22020 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f  entation.** is o
22030 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d  nly capable of m
22040 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c  illisecond resol
22050 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78  ution so the six
22060 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61   least significa
22070 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20  nt.** digits in 
22080 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61  the time are mea
22090 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72  ningless.  Futur
220a0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
220b0 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72  Lite.** might pr
220c0 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65  ovide greater re
220d0 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20  solution on the 
220e0 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63  profiler callbac
220f0 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  k.  The.** sqlit
22100 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e  e3_profile() fun
22110 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65  ction is conside
22120 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
22130 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65   and is.** subje
22140 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
22150 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
22160 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
22170 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
22180 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
22190 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ace(sqlite3*,.  
221a0 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
221b0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
221c0 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
221d0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
221e0 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
221f0 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
22200 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
22210 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
22220 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
22230 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
22240 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
22250 54 72 61 63 65 20 45 76 65 6e 74 20 43 6f 64 65  Trace Event Code
22260 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
22270 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a  QLITE_TRACE.**.*
22280 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
22290 73 20 69 64 65 6e 74 69 66 79 20 63 6c 61 73 73  s identify class
222a0 65 73 20 6f 66 20 65 76 65 6e 74 73 20 74 68 61  es of events tha
222b0 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f 72  t can be monitor
222c0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20  ed.** using the 
222d0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
222e0 32 28 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f 67  2()] tracing log
222f0 69 63 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  ic.  The third a
22300 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73  rgument.** to [s
22310 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
22320 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63  )] is an OR-ed c
22330 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e  ombination of on
22340 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20  e or more of.** 
22350 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f  the following co
22360 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66  nstants.  ^The f
22370 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
22380 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62   the trace callb
22390 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66  ack.** is one of
223a0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
223b0 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  onstants..**.** 
223c0 4e 65 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73  New tracing cons
223d0 74 61 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64  tants may be add
223e0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
223f0 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  eases..**.** ^A 
22400 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68  trace callback h
22410 61 73 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74  as four argument
22420 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43  s: xCallback(T,C
22430 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54  ,P,X)..** ^The T
22440 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
22450 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   of the integer 
22460 74 79 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65  type codes above
22470 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75  ..** ^The C argu
22480 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f  ment is a copy o
22490 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f  f the context po
224a0 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 20  inter passed in 
224b0 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  as the.** fourth
224c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
224d0 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
224e0 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20  ]..** The P and 
224f0 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20  X arguments are 
22500 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d  pointers whose m
22510 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f  eanings depend o
22520 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  n T..**.** <dl>.
22530 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
22540 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c  E_STMT]] <dt>SQL
22550 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f  ITE_TRACE_STMT</
22560 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
22570 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54  QLITE_TRACE_STMT
22580 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
22590 6f 6b 65 64 20 77 68 65 6e 20 61 20 70 72 65 70  oked when a prep
225a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
225b0 2a 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 72  * first begins r
225c0 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69  unning and possi
225d0 62 6c 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d  bly at other tim
225e0 65 73 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  es during the.**
225f0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
22600 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
22610 6d 65 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74  ment, such as at
22620 20 74 68 65 20 73 74 61 72 74 20 6f 66 20 65 61   the start of ea
22630 63 68 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75  ch.** trigger su
22640 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50  bprogram. ^The P
22650 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
22660 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
22670 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22680 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72  ment]. ^The X ar
22690 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
226a0 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
226b0 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
226c0 75 6e 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74  unexpanded SQL t
226d0 65 78 74 20 6f 66 20 74 68 65 20 70 72 65 70 61  ext of the prepa
226e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  red statement or
226f0 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20   an SQL comment 
22700 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74  .** that indicat
22710 65 73 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f  es the invocatio
22720 6e 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20  n of a trigger. 
22730 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63   ^The callback c
22740 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68  an compute.** th
22750 65 20 73 61 6d 65 20 74 65 78 74 20 74 68 61 74  e same text that
22760 20 77 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e   would have been
22770 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
22780 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
22790 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74  _trace()].** int
227a0 65 72 66 61 63 65 20 62 79 20 75 73 69 6e 67 20  erface by using 
227b0 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77  the X argument w
227c0 68 65 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74  hen X begins wit
227d0 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b  h "--" and invok
227e0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
227f0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d  expanded_sql(P)]
22800 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
22810 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
22820 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53  _PROFILE]] <dt>S
22830 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
22840 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ILE</dt>.** <dd>
22850 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
22860 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63  _PROFILE callbac
22870 6b 20 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f  k provides appro
22880 78 69 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d  ximately the sam
22890 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
228a0 20 61 73 20 69 73 20 70 72 6f 76 69 64 65 64 20   as is provided 
228b0 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
228c0 70 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62  profile()] callb
228d0 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61  ack..** ^The P a
228e0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
228f0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65  nter to the [pre
22900 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22910 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72   and the.** X ar
22920 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
22930 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65   a 64-bit intege
22940 72 20 77 68 69 63 68 20 69 73 20 74 68 65 20 65  r which is the e
22950 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74  stimated of.** t
22960 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e  he number of nan
22970 6f 73 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65  osecond that the
22980 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
22990 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
229a0 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  .** ^The SQLITE_
229b0 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61  TRACE_PROFILE ca
229c0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
229d0 64 20 77 68 65 6e 20 74 68 65 20 73 74 61 74 65  d when the state
229e0 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a  ment finishes..*
229f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
22a00 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51  ACE_ROW]] <dt>SQ
22a10 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f  LITE_TRACE_ROW</
22a20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
22a30 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20  QLITE_TRACE_ROW 
22a40 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
22a50 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 70  ked whenever a p
22a60 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
22a70 6d 65 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61  ment generates a
22a80 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72   single row of r
22a90 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65  esult.  .** ^The
22aa0 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
22ab0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
22ac0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22ad0 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  ent] and the.** 
22ae0 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e  X argument is un
22af0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  used..**.** [[SQ
22b00 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
22b10 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
22b20 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a  ACE_CLOSE</dt>.*
22b30 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
22b40 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c  _TRACE_CLOSE cal
22b50 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
22b60 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
22b70 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  .** connection c
22b80 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50  loses..** ^The P
22b90 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
22ba0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
22bb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
22bc0 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  on] object.** an
22bd0 64 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74  d the X argument
22be0 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c   is unused..** <
22bf0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
22c00 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
22c10 54 20 20 20 20 20 20 20 30 78 30 31 0a 23 64 65  T       0x01.#de
22c20 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
22c30 45 5f 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30  E_PROFILE    0x0
22c40 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
22c50 5f 54 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20  _TRACE_ROW      
22c60 20 20 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53    0x04.#define S
22c70 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
22c80 45 20 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a  E      0x08../*.
22c90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
22ca0 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d   Trace Hook.** M
22cb0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
22cc0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
22cd0 33 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58  3_trace_v2(D,M,X
22ce0 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,P) interface re
22cf0 67 69 73 74 65 72 73 20 61 20 74 72 61 63 65 20  gisters a trace 
22d00 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
22d10 74 69 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b  tion X against [
22d20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22d30 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72  ion] D, using pr
22d40 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a  operty mask M.**
22d50 20 61 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69   and context poi
22d60 6e 74 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65  nter P.  ^If the
22d70 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a   X callback is.*
22d80 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65  * NULL or if the
22d90 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c   M mask is zero,
22da0 20 74 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73   then tracing is
22db0 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a   disabled.  The.
22dc0 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68  ** M argument sh
22dd0 6f 75 6c 64 20 62 65 20 74 68 65 20 62 69 74 77  ould be the bitw
22de0 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e  ise OR-ed combin
22df0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f  ation of.** zero
22e00 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45   or more [SQLITE
22e10 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74  _TRACE] constant
22e20 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63  s..**.** ^Each c
22e30 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71  all to either sq
22e40 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72  lite3_trace() or
22e50 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
22e60 32 28 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a  2() overrides .*
22e70 2a 20 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20  * (cancels) any 
22e80 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73  prior calls to s
22e90 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f  qlite3_trace() o
22ea0 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  r sqlite3_trace_
22eb0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  v2()..**.** ^The
22ec0 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69   X callback is i
22ed0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
22ee0 61 6e 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74  any of the event
22ef0 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
22f00 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72  .** mask M occur
22f10 2e 20 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20  .  ^The integer 
22f20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
22f30 6d 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  m the callback i
22f40 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69  s currently.** i
22f50 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74  gnored, though t
22f60 68 69 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69  his may change i
22f70 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
22f80 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s.  Callback.** 
22f90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
22fa0 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65  should return ze
22fb0 72 6f 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74  ro to ensure fut
22fc0 75 72 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ure compatibilit
22fd0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63  y..**.** ^A trac
22fe0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
22ff0 76 6f 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20  voked with four 
23000 61 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62  arguments: callb
23010 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a  ack(T,C,P,X)..**
23020 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74   ^The T argument
23030 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
23040 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a  SQLITE_TRACE].**
23050 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e   constants to in
23060 64 69 63 61 74 65 20 77 68 79 20 74 68 65 20 63  dicate why the c
23070 61 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f  allback was invo
23080 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61  ked..** ^The C a
23090 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70  rgument is a cop
230a0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74  y of the context
230b0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65   pointer..** The
230c0 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e   P and X argumen
230d0 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20  ts are pointers 
230e0 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64  whose meanings d
230f0 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a  epend on T..**.*
23100 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72  * The sqlite3_tr
23110 61 63 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61  ace_v2() interfa
23120 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  ce is intended t
23130 6f 20 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65  o replace the le
23140 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
23150 65 73 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  es [sqlite3_trac
23160 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
23170 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f  3_profile()], bo
23180 74 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61  th of which.** a
23190 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a  re deprecated..*
231a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  /.int sqlite3_tr
231b0 61 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ace_v2(.  sqlite
231c0 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75  3*,.  unsigned u
231d0 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61  Mask,.  int(*xCa
231e0 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64  llback)(unsigned
231f0 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69  ,void*,void*,voi
23200 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74  d*),.  void *pCt
23210 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x.);../*.** CAPI
23220 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
23230 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
23240 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
23250 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
23260 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
23270 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
23280 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
23290 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
232a0 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
232b0 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
232c0 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
232d0 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
232e0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
232f0 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
23300 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
23310 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
23320 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
23330 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
23340 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
23350 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
23360 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
23370 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
23380 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
23390 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
233a0 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
233b0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
233c0 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
233d0 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
233e0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
233f0 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
23400 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70  eter N is the ap
23410 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72  proximate number
23420 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
23430 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
23440 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
23450 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
23460 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
23470 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
23480 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20  he callback X.  
23490 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68  ^If N is less th
234a0 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20  an one then the 
234b0 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64  progress.** hand
234c0 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ler is disabled.
234d0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
234e0 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
234f0 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
23500 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
23510 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
23520 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
23530 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
23540 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
23550 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
23560 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
23570 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
23580 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
23590 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
235a0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
235b0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
235c0 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
235d0 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
235e0 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
235f0 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
23600 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
23610 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
23620 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
23630 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
23640 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
23650 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
23660 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
23670 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
23680 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
23690 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
236a0 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
236b0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
236c0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
236d0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
236e0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
236f0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
23700 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
23710 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
23720 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
23730 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
23740 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
23750 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
23760 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
23770 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
23780 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
23790 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
237a0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
237b0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
237c0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
237d0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
237e0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
237f0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
23800 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
23810 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
23820 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
23830 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e  onnection.** CON
23840 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
23850 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  3.**.** ^These r
23860 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
23870 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
23880 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65  file as specifie
23890 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c  d by the .** fil
238a0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
238b0 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72  ^The filename ar
238c0 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
238d0 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
238e0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
238f0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
23900 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
23910 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
23920 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
23930 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
23940 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b  _open16(). ^(A [
23950 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23960 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  ion] handle is u
23970 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e  sually.** return
23980 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
23990 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  n if an error oc
239a0 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
239b0 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61  exception is tha
239c0 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  t.** if SQLite i
239d0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
239e0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
239f0 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  old the [sqlite3
23a00 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e  ] object,.** a N
23a10 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74  ULL will be writ
23a20 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69  ten into *ppDb i
23a30 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e  nstead of a poin
23a40 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
23a50 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29  te3].** object.)
23a60 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62  ^ ^(If the datab
23a70 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
23a80 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73  nd/or created) s
23a90 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
23aa0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  n.** [SQLITE_OK]
23ab0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
23ac0 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
23ad0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
23ae0 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20  rned.)^ ^The.** 
23af0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
23b00 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
23b10 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69  rrmsg16()] routi
23b20 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
23b30 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
23b40 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
23b50 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
23b60 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77  the error follow
23b70 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66  ing a failure of
23b80 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73   any.** of the s
23b90 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f  qlite3_open() ro
23ba0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  utines..**.** ^T
23bb0 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
23bc0 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ing will be UTF-
23bd0 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20  8 for databases 
23be0 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
23bf0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
23c00 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
23c10 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61  v2().  ^The defa
23c20 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
23c30 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72   databases.** cr
23c40 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69  eated using sqli
23c50 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c  te3_open16() wil
23c60 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74  l be UTF-16 in t
23c70 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
23c80 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  rder..**.** Whet
23c90 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
23ca0 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
23cb0 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
23cc0 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
23cd0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
23ce0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23cf0 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
23d00 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
23d10 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
23d20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
23d30 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
23d40 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
23d50 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
23d60 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
23d70 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
23d80 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
23d90 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
23da0 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
23db0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
23dc0 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
23dd0 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
23de0 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
23df0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23e00 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
23e10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
23e20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23e30 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
23e40 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
23e50 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
23e60 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
23e70 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
23e80 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
23e90 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
23ea0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
23eb0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
23ec0 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
23ed0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
23ee0 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64  IVATECACHE], and
23ef0 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
23f00 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  _URI] flags:)^.*
23f10 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
23f20 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
23f30 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
23f40 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
23f50 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
23f60 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
23f70 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
23f80 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
23f90 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
23fa0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
23fb0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
23fc0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
23fd0 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
23fe0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
23ff0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
24000 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
24010 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
24020 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
24030 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
24040 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
24050 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
24060 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
24070 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
24080 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
24090 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
240a0 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
240b0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
240c0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
240d0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
240e0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
240f0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
24100 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
24110 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
24120 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
24130 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
24140 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64  , and is created
24150 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
24160 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
24170 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
24180 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
24190 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
241a0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
241b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
241c0 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
241d0 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
241e0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
241f0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
24200 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
24210 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
24220 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
24230 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  bove optionally 
24240 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74  combined with ot
24250 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  her.** [SQLITE_O
24260 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53  PEN_READONLY | S
24270 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74  QLITE_OPEN_* bit
24280 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s].** then the b
24290 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
242a0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
242b0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
242c0 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
242d0 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
242e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
242f0 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
24300 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
24310 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
24320 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
24330 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
24340 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
24350 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
24360 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
24370 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
24380 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
24390 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
243a0 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
243b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
243c0 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
243d0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
243e0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
243f0 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
24400 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
24410 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
24420 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
24430 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
24440 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
24450 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
24460 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
24470 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24480 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
24490 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
244a0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
244b0 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
244c0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
244d0 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
244e0 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
244f0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
24500 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
24510 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
24520 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
24530 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
24540 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
24550 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
24560 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
24570 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
24580 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
24590 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
245a0 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
245b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
245c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
245d0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
245e0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
245f0 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
24600 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
24610 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
24620 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
24630 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
24640 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
24650 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
24660 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
24670 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
24680 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
24690 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
246a0 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
246b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
246c0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
246d0 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
246e0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
246f0 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
24700 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
24710 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
24720 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
24730 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
24740 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
24750 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
24760 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
24770 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
24780 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
24790 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
247a0 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
247b0 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
247c0 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
247d0 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
247e0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
247f0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
24800 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
24810 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
24820 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
24830 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
24840 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
24850 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
24860 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
24870 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
24880 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
24890 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
248a0 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
248b0 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
248c0 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
248d0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
248e0 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
248f0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
24900 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
24910 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
24920 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
24930 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
24940 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
24950 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24960 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
24970 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
24980 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70  es in sqlite3_op
24990 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46  en()]] <h3>URI F
249a0 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a  ilenames</h3>.**
249b0 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c  .** ^If [URI fil
249c0 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74  ename] interpret
249d0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
249e0 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61  , and the filena
249f0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62  me argument.** b
24a00 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65  egins with "file
24a10 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c  :", then the fil
24a20 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72  ename is interpr
24a30 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e  eted as a URI. ^
24a40 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  URI.** filename 
24a50 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
24a60 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
24a70 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
24a80 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65  I] flag is.** se
24a90 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20  t in the fourth 
24aa0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
24ab0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f  te3_open_v2(), o
24ac0 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62  r if it has.** b
24ad0 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62  een enabled glob
24ae0 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b  ally using the [
24af0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
24b00 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74  I] option with t
24b10 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
24b20 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20  onfig()] method 
24b30 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  or by the [SQLIT
24b40 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69  E_USE_URI] compi
24b50 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
24b60 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20  ** As of SQLite 
24b70 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55  version 3.7.7, U
24b80 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  RI filename inte
24b90 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75  rpretation is tu
24ba0 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64  rned off.** by d
24bb0 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75  efault, but futu
24bc0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
24bd0 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62  QLite might enab
24be0 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a  le URI filename.
24bf0 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  ** interpretatio
24c00 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53  n by default.  S
24c10 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ee "[URI filenam
24c20 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f  es]" for additio
24c30 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
24c40 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69  on..**.** URI fi
24c50 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73  lenames are pars
24c60 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  ed according to 
24c70 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68  RFC 3986. ^If th
24c80 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61  e URI contains a
24c90 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20  n.** authority, 
24ca0 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20  then it must be 
24cb0 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20  either an empty 
24cc0 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74  string or the st
24cd0 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68  ring .** "localh
24ce0 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75  ost". ^If the au
24cf0 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61  thority is not a
24d00 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
24d10 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61  r "localhost", a
24d20 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72  n .** error is r
24d30 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63  eturned to the c
24d40 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67  aller. ^The frag
24d50 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  ment component o
24d60 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20  f a URI, if .** 
24d70 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f  present, is igno
24d80 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  red..**.** ^SQLi
24d90 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68  te uses the path
24da0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68   component of th
24db0 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d  e URI as the nam
24dc0 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  e of the disk fi
24dd0 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74  le.** which cont
24de0 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  ains the databas
24df0 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  e. ^If the path 
24e00 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f  begins with a '/
24e10 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a  ' character, .**
24e20 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65   then it is inte
24e30 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62  rpreted as an ab
24e40 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66  solute path. ^If
24e50 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e   the path does n
24e60 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74  ot begin .** wit
24e70 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67  h a '/' (meaning
24e80 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
24e90 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f  ity section is o
24ea0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
24eb0 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  URI).** then the
24ec0 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72   path is interpr
24ed0 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69  eted as a relati
24ee0 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f  ve path. .** ^(O
24ef0 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66  n windows, the f
24f00 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  irst component o
24f10 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  f an absolute pa
24f20 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76  th .** is a driv
24f30 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  e specification 
24f40 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a  (e.g. "C:").)^.*
24f50 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20  *.** [[core URI 
24f60 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
24f70 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20  ]].** The query 
24f80 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
24f90 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70  RI may contain p
24fa0 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61  arameters that a
24fb0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a  re interpreted.*
24fc0 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69  * either by SQLi
24fd0 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79  te itself, or by
24fe0 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d   a [VFS | custom
24ff0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
25000 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  ion]..** SQLite 
25010 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e  and its built-in
25020 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72   [VFSes] interpr
25030 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  et the.** follow
25040 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d 65  ing query parame
25050 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ters:.**.** <ul>
25060 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66  .**   <li> <b>vf
25070 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73  s</b>: ^The "vfs
25080 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  " parameter may 
25090 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69  be used to speci
250a0 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a  fy the name of.*
250b0 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65  *     a VFS obje
250c0 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73  ct that provides
250d0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
250e0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
250f0 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20  that should.**  
25100 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63     be used to ac
25110 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
25120 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20  e file on disk. 
25130 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ^If this option 
25140 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20  is set to.**    
25150 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
25160 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
25170 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
25180 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
25190 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56  unknown.**     V
251a0 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  FS is an error. 
251b0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
251c0 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
251d0 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e  d the vfs option
251e0 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65   is.**     prese
251f0 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53  nt, then the VFS
25200 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
25210 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70  e option takes p
25220 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a  recedence over.*
25230 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20  *     the value 
25240 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
25250 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
25260 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
25270 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
25280 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e  > <b>mode</b>: ^
25290 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65  (The mode parame
252a0 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
252b0 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22  o either "ro", "
252c0 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63  rw",.**     "rwc
252d0 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20  ", or "memory". 
252e0 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
252f0 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
25300 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20  r value is.**   
25310 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a    an error)^. .*
25320 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
25330 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
25340 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
25350 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
25360 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
25370 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
25380 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
25390 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
253a0 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
253b0 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
253c0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
253d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
253e0 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
253f0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
25400 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
25410 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
25420 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
25430 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
25440 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
25450 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
25460 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
25470 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
25480 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
25490 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
254a0 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
254b0 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
254c0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
254d0 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
254e0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
254f0 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
25500 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20  EN_CREATE.  ^If 
25510 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
25520 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f  is.**     set to
25530 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61   "memory" then a
25540 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79   pure [in-memory
25550 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20   database] that 
25560 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20  never reads.**  
25570 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f     or writes fro
25580 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20  m disk is used. 
25590 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20  ^It is an error 
255a0 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
255b0 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68  ue for.**     th
255c0 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
255d0 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65   that is less re
255e0 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
255f0 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
25600 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67  .**     the flag
25610 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20  s passed in the 
25620 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
25630 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
25640 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
25650 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
25660 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
25670 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
25680 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
25690 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
256a0 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
256b0 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
256c0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
256d0 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
256e0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
256f0 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
25700 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
25710 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
25720 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
25730 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
25740 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
25750 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
25760 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
25770 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
25780 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
25790 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
257a0 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
257b0 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
257c0 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
257d0 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
257e0 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
257f0 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
25800 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
25810 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
25820 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71  any behavior req
25830 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e  uested by settin
25840 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  g.**     SQLITE_
25850 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
25860 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e  E or SQLITE_OPEN
25870 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61  _SHAREDCACHE fla
25880 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  g..**.**  <li> <
25890 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65  b>psow</b>: ^The
258a0 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20   psow parameter 
258b0 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 65  indicates whethe
258c0 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20  r or not the.** 
258d0 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f      [powersafe o
258e0 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72  verwrite] proper
258f0 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20  ty does or does 
25900 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65  not apply to the
25910 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20  .**     storage 
25920 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74  media on which t
25930 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
25940 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20   resides..**.** 
25950 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c   <li> <b>nolock<
25960 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b  /b>: ^The nolock
25970 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
25980 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61  boolean query pa
25990 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77  rameter.**     w
259a0 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61  hich if set disa
259b0 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e  bles file lockin
259c0 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f  g in rollback jo
259d0 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68  urnal modes.  Th
259e0 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65  is.**     is use
259f0 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e  ful for accessin
25a00 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20  g a database on 
25a10 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61  a filesystem tha
25a20 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20  t does not.**   
25a30 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e    support lockin
25a40 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61  g.  Caution:  Da
25a50 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
25a60 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  n might result i
25a70 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20  f two.**     or 
25a80 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77  more processes w
25a90 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65  rite to the same
25aa0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e   database and an
25ab0 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a  y one of those.*
25ac0 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20  *     processes 
25ad0 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a  uses nolock=1..*
25ae0 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d  *.**  <li> <b>im
25af0 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68  mutable</b>: ^Th
25b00 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61  e immutable para
25b10 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
25b20 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20  an query.**     
25b30 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
25b40 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
25b50 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
25b60 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20  is stored on.** 
25b70 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65      read-only me
25b80 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75  dia.  ^When immu
25b90 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51  table is set, SQ
25ba0 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
25bb0 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74  t the.**     dat
25bc0 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f  abase file canno
25bd0 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76  t be changed, ev
25be0 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20  en by a process 
25bf0 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20  with higher.**  
25c00 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e     privilege, an
25c10 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73  d so the databas
25c20 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64  e is opened read
25c30 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f  -only and all lo
25c40 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64  cking.**     and
25c50 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f   change detectio
25c60 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20  n is disabled.  
25c70 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67  Caution: Setting
25c80 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a   the immutable.*
25c90 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f  *     property o
25ca0 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
25cb0 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66  e that does in f
25cc0 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72  act change can r
25cd0 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20  esult.**     in 
25ce0 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20  incorrect query 
25cf0 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b  results and/or [
25d00 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20  SQLITE_CORRUPT] 
25d10 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53  errors..**     S
25d20 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
25d30 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
25d40 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20  ]..**       .** 
25d50 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65  </ul>.**.** ^Spe
25d60 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
25d70 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  wn parameter in 
25d80 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  the query compon
25d90 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20  ent of a URI is 
25da0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e  not an.** error.
25db0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
25dc0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
25dd0 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64  t understand add
25de0 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a  itional query.**
25df0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65   parameters.  Se
25e00 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65  e "[query parame
25e10 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61  ters with specia
25e20 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c  l meaning to SQL
25e30 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64  ite]" for.** add
25e40 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
25e50 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  ion..**.** [[URI
25e60 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
25e70 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c  es]] <h3>URI fil
25e80 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f  ename examples</
25e90 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65  h3>.**.** <table
25ea0 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67   border="1" alig
25eb0 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64  n=center cellpad
25ec0 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c  ding=5>.** <tr><
25ed0 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  th> URI filename
25ee0 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a  s <th> Results.*
25ef0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
25f00 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
25f10 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
25f20 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
25f30 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
25f40 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c   directory..** <
25f50 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
25f60 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c  me/fred/data.db<
25f70 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  br>.**          
25f80 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65  file:///home/fre
25f90 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a  d/data.db <br> .
25fa0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
25fb0 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d  ://localhost/hom
25fc0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
25fd0 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  br> <td> .**    
25fe0 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64        Open the d
25ff0 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68  atabase file "/h
26000 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
26010 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
26020 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68  ile://darkstar/h
26030 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
26040 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
26050 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61     An error. "da
26060 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61  rkstar" is not a
26070 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68   recognized auth
26080 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ority..** <tr><t
26090 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73  d style="white-s
260a0 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a  pace:nowrap"> .*
260b0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
260c0 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25  ///C:/Documents%
260d0 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73  20and%20Settings
260e0 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61  /fred/Desktop/da
260f0 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64  ta.db.**     <td
26100 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20  > Windows only: 
26110 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
26120 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27  ata.db" on fred'
26130 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69  s desktop on dri
26140 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43  ve.**          C
26150 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  :. Note that the
26160 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e   %20 escaping in
26170 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73   this example is
26180 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a   not strictly .*
26190 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73  *          neces
261a0 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61  sary - space cha
261b0 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75  racters can be u
261c0 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a  sed literally.**
261d0 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49            in URI
261e0 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c   filenames..** <
261f0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
26200 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63  a.db?mode=ro&cac
26210 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20  he=private <td> 
26220 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
26230 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  n file "data.db"
26240 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
26250 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65  directory for re
26260 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a  ad-only access..
26270 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61  **          Rega
26280 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
26290 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d  r or not shared-
262a0 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e  cache mode is en
262b0 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  abled by.**     
262c0 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73       default, us
262d0 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68  e a private cach
262e0 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  e..** <tr><td> f
262f0 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
26300 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d  ata.db?vfs=unix-
26310 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20  dotfile <td>.** 
26320 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
26330 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
26340 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65  ata.db". Use the
26350 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e   special VFS "un
26360 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20  ix-dotfile".**  
26370 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65          that use
26380 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70  s dot-files in p
26390 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64  lace of posix ad
263a0 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a  visory locking..
263b0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
263c0 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65  :data.db?mode=re
263d0 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20  adonly <td> .** 
263e0 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
263f0 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73  r. "readonly" is
26400 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74   not a valid opt
26410 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64  ion for the "mod
26420 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  e" parameter..**
26430 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20   </table>.**.** 
26440 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c  ^URI hexadecimal
26450 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
26460 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70  s (%HH) are supp
26470 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65  orted within the
26480 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65   path and.** que
26490 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
264a0 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65   a URI. A hexade
264b0 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
264c0 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f  uence consists o
264d0 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73  f a.** percent s
264e0 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c  ign - "%" - foll
264f0 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20  owed by exactly 
26500 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20  two hexadecimal 
26510 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69  digits .** speci
26520 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76  fying an octet v
26530 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68  alue. ^Before th
26540 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20  e path or query 
26550 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a  components of a.
26560 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  ** URI filename 
26570 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c  are interpreted,
26580 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65   they are encode
26590 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e  d using UTF-8 an
265a0 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65  d all .** hexade
265b0 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
265c0 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20  uences replaced 
265d0 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65  by a single byte
265e0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a   containing the.
265f0 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ** corresponding
26600 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20   octet. If this 
26610 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65  process generate
26620 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46  s an invalid UTF
26630 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20  -8 encoding,.** 
26640 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
26650 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
26660 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
26670 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
26680 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
26690 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
266a0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
266b0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
266c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
266d0 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
266e0 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
266f0 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
26700 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
26710 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
26720 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
26730 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
26740 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
26750 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
26760 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
26770 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
26780 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
26790 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
267a0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  2()..**.** <b>No
267b0 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75  te to Windows Ru
267c0 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e  ntime users:</b>
267d0 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20    The temporary 
267e0 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62  directory must b
267f0 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74  e set.** prior t
26800 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  o calling sqlite
26810 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
26820 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
26830 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f  Otherwise, vario
26840 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74  us.** features t
26850 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20  hat require the 
26860 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79  use of temporary
26870 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e   files may fail.
26880 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
26890 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   [sqlite3_temp_d
268a0 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74  irectory].*/.int
268b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20   sqlite3_open(. 
268c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
268d0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
268e0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
268f0 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
26900 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
26910 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
26920 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
26930 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
26940 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
26950 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
26960 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
26970 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
26980 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
26990 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
269a0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
269b0 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
269c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
269d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
269e0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
269f0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
26a00 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
26a10 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
26a20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
26a30 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
26a40 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
26a50 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
26a60 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
26a70 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
26a80 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
26a90 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
26aa0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26ab0 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73  F: Obtain Values
26ac0 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74   For URI Paramet
26ad0 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ers.**.** These 
26ae0 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74  are utility rout
26af0 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20  ines, useful to 
26b00 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
26b10 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a  ons, that check.
26b20 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64  ** to see if a d
26b30 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73  atabase file was
26b40 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74   a URI that cont
26b50 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63  ained a specific
26b60 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d   query .** param
26b70 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20  eter, and if so 
26b80 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75  obtains the valu
26b90 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20  e of that query 
26ba0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
26bb0 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74   If F is the dat
26bc0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70  abase filename p
26bd0 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
26be0 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d  to the xOpen() m
26bf0 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56  ethod of .** a V
26c00 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
26c10 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73  n when the flags
26c20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
26c30 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72  pen() has one or
26c40 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65   .** more of the
26c50 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
26c60 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  I] or [SQLITE_OP
26c70 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73  EN_MAIN_DB] bits
26c80 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73   set and.** P is
26c90 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
26ca0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
26cb0 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
26cc0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
26cd0 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65  F,P) returns the
26ce0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a   value of the P.
26cf0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20  ** parameter if 
26d00 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e  it exists or a N
26d10 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50  ULL pointer if P
26d20 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72   does not appear
26d30 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20   as a .** query 
26d40 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20  parameter on F. 
26d50 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79   If P is a query
26d60 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a   parameter of F.
26d70 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63  ** has no explic
26d80 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73  it value, then s
26d90 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
26da0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
26db0 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
26dc0 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  o an empty strin
26dd0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  g..**.** The sql
26de0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
26df0 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
26e00 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69  assumes that P i
26e10 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70  s a boolean.** p
26e20 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
26e30 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72  urns true (1) or
26e40 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72   false (0) accor
26e50 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75  ding to the valu
26e60 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20  e.** of P.  The 
26e70 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
26e80 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
26e90 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ne returns true 
26ea0 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61  (1) if the.** va
26eb0 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72  lue of query par
26ec0 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
26ed0 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22  of "yes", "true"
26ee0 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79  , or "on" in any
26ef0 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74  .** case or if t
26f00 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
26f10 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  with a non-zero 
26f20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a  number.  The .**
26f30 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
26f40 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
26f50 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c  ines returns fal
26f60 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61  se (0) if the va
26f70 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20  lue of.** query 
26f80 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
26f90 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c  ne of "no", "fal
26fa0 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e  se", or "off" in
26fb0 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20   any case or.** 
26fc0 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
26fd0 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72  ins with a numer
26fe0 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69  ic zero.  If P i
26ff0 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a  s not a query.**
27000 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20   parameter on F 
27010 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
27020 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74  of P is does not
27030 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68   match any of th
27040 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e  e.** above, then
27050 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
27060 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
27070 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a  rns (B!=0)..**.*
27080 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
27090 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72  i_int64(F,P,D) r
270a0 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20  outine converts 
270b0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
270c0 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20  nto a.** 64-bit 
270d0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
270e0 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20  nd returns that 
270f0 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66  integer, or D if
27100 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65   P does not.** e
27110 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61  xist.  If the va
27120 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65  lue of P is some
27130 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
27140 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
27150 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74  n.** zero is ret
27160 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66  urned..** .** If
27170 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   F is a NULL poi
27180 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74  nter, then sqlit
27190 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
271a0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55  (F,P) returns NU
271b0 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  LL and.** sqlite
271c0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
271d0 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20  P,B) returns B. 
271e0 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e   If F is not a N
271f0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a  ULL pointer and.
27200 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  ** is not a data
27210 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61  base file pathna
27220 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  me pointer that 
27230 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e  SQLite passed in
27240 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
27250 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  VFS method, then
27260 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
27270 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
27280 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
27290 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73  robably.** undes
272a0 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74  irable..*/.const
272b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75   char *sqlite3_u
272c0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e  ri_parameter(con
272d0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
272e0 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  me, const char *
272f0 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c  zParam);.int sql
27300 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
27310 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
27320 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  le, const char *
27330 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66  zParam, int bDef
27340 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69  ault);.sqlite3_i
27350 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69  nt64 sqlite3_uri
27360 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61  _int64(const cha
27370 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  r*, const char*,
27380 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
27390 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
273a0 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41  F: Error Codes A
273b0 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d  nd Messages.** M
273c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
273d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
273e0 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33  t recent sqlite3
273f0 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f  _* API call asso
27400 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20  ciated with .** 
27410 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
27420 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20  tion] D failed, 
27430 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
27440 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65  _errcode(D) inte
27450 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73  rface.** returns
27460 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
27470 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65  sult code] or [e
27480 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
27490 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a  ode] for that.**
274a0 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66   API call..** If
274b0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
274c0 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75   API call was su
274d0 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65  ccessful,.** the
274e0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
274f0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
27500 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
27510 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  efined..** ^The 
27520 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
27530 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
27540 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
27550 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
27560 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
27570 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
27580 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
27590 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
275a0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
275b0 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
275c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
275d0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
275e0 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
275f0 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
27600 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
27610 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
27620 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
27630 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
27640 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
27650 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
27660 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
27670 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
27680 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
27690 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
276a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
276b0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
276c0 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
276d0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
276e0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
276f0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
27700 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
27710 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
27720 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
27730 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
27740 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
27750 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
27760 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27770 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66  _errstr() interf
27780 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
27790 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
277a0 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65   text.** that de
277b0 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73  scribes the [res
277c0 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54  ult code], as UT
277d0 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  F-8..** ^(Memory
277e0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
277f0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
27800 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
27810 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d  ernally.** and m
27820 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64  ust not be freed
27830 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
27840 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ion)^..**.** Whe
27850 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
27860 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
27870 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
27880 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
27890 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
278a0 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
278b0 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
278c0 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
278d0 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
278e0 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
278f0 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
27900 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
27910 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
27920 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
27930 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
27940 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
27950 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
27960 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
27970 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
27980 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
27990 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
279a0 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
279b0 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
279c0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
279d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
279e0 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
279f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
27a00 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
27a10 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
27a20 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
27a30 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
27a40 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
27a50 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
27a60 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
27a70 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
27a80 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
27a90 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
27aa0 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
27ab0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
27ac0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
27ad0 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
27ae0 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
27af0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
27b00 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
27b10 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
27b20 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
27b30 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
27b40 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
27b50 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
27b60 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
27b70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
27b80 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
27b90 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
27ba0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
27bb0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
27bc0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
27bd0 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
27be0 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
27bf0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
27c00 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  6(sqlite3*);.con
27c10 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
27c20 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f  _errstr(int);../
27c30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
27c40 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
27c50 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  t Object.** KEYW
27c60 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20  ORDS: {prepared 
27c70 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70  statement} {prep
27c80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d  ared statements}
27c90 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
27ca0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
27cb0 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73  t represents a s
27cc0 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
27cd0 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20  ent that.** has 
27ce0 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e  been compiled in
27cf0 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61  to binary form a
27d00 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f 20 62  nd is ready to b
27d10 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a  e evaluated..**.
27d20 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68  ** Think of each
27d30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
27d40 73 20 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d  s a separate com
27d50 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20  puter program.  
27d60 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  The.** original 
27d70 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72  SQL text is sour
27d80 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70  ce code.  A prep
27d90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
27da0 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65  bject .** is the
27db0 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74   compiled object
27dc0 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20   code.  All SQL 
27dd0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
27de0 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70  d into a.** prep
27df0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62  ared statement b
27e00 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20  efore it can be 
27e10 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  run..**.** The l
27e20 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70  ife-cycle of a p
27e30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27e40 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79  t object usually
27e50 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a   goes like this:
27e60 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
27e70 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 70  li> Create the p
27e80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27e90 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  t object using [
27ea0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
27eb0 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  v2()]..** <li> B
27ec0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70  ind values to [p
27ed0 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67  arameters] using
27ee0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
27ef0 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e  d_*().**      in
27f00 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69  terfaces..** <li
27f10 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
27f20 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
27f30 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
27f40 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
27f50 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 70  <li> Reset the p
27f60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27f70 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
27f80 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
27f90 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
27fa0 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
27fb0 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
27fc0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
27fd0 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
27fe0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
27ff0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
28000 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65   </ol>.*/.typede
28010 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
28020 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
28030 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
28040 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
28050 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  mits.** METHOD: 
28060 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28  sqlite3.**.** ^(
28070 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
28080 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
28090 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
280a0 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
280b0 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
280c0 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
280d0 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
280e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
280f0 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
28100 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
28110 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
28120 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
28130 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
28140 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
28150 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
28160 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
28170 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
28180 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
28190 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
281a0 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
281b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
281c0 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
281d0 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
281e0 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uct.)^.**.** ^If
281f0 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
28200 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
28210 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
28220 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
28230 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74  ^(For each limit
28240 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45   category SQLITE
28250 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f  _LIMIT_<i>NAME</
28260 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  i> there is a .*
28270 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
28280 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
28290 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
282a0 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70  time by a C prep
282b0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63  rocessor macro c
282c0 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73  alled.** [limits
282d0 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69   | SQLITE_MAX_<i
282e0 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28  >NAME</i>]..** (
282f0 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e  The "_LIMIT_" in
28300 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61   the name is cha
28310 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e  nged to "_MAX_".
28320 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73  ))^.** ^Attempts
28330 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c   to increase a l
28340 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68  imit above its h
28350 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
28360 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20  are.** silently 
28370 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65  truncated to the
28380 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
28390 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64  d..**.** ^Regard
283a0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
283b0 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74  or not the limit
283c0 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68   was changed, th
283d0 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  e .** [sqlite3_l
283e0 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63  imit()] interfac
283f0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72  e returns the pr
28400 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65  ior value of the
28410 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63   limit..** ^Henc
28420 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63  e, to find the c
28430 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20  urrent value of 
28440 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20  a limit without 
28450 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20  changing it,.** 
28460 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68  simply invoke th
28470 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74  is interface wit
28480 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  h the third para
28490 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e  meter set to -1.
284a0 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20  .**.** Run-time 
284b0 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
284c0 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
284d0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
284e0 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
284f0 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
28500 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
28510 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
28520 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
28530 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
28540 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
28550 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
28560 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
28570 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62  ht be a.** web b
28580 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20  rowser that has 
28590 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65  its own database
285a0 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69  s for storing hi
285b0 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70  story and.** sep
285c0 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20  arate databases 
285d0 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61  controlled by Ja
285e0 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61  vaScript applica
285f0 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64  tions downloaded
28600 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65  .** off the Inte
28610 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72  rnet.  The inter
28620 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61  nal databases ca
28630 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a  n be given the.*
28640 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74  * large, default
28650 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61   limits.  Databa
28660 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65  ses managed by e
28670 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20  xternal sources 
28680 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20  can.** be given 
28690 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d  much smaller lim
286a0 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20  its designed to 
286b0 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c  prevent a denial
286c0 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61   of service.** a
286d0 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65  ttack.  Develope
286e0 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61  rs might also wa
286f0 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73  nt to use the [s
28700 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
28710 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65  rizer()].** inte
28720 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72  rface to further
28730 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74   control untrust
28740 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a  ed SQL.  The siz
28750 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
28760 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  e.** created by 
28770 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72  an untrusted scr
28780 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61  ipt can be conta
28790 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ined using the.*
287a0 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  * [max_page_coun
287b0 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a  t] [PRAGMA]..**.
287c0 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20  ** New run-time 
287d0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
287e0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
287f0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
28800 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
28810 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
28820 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
28830 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
28840 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
28850 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
28860 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
28870 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
28880 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
28890 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
288a0 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
288b0 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
288c0 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
288d0 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
288e0 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
288f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
28900 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
28910 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
28920 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
28930 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
28940 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
28950 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
28960 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
28970 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
28980 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
28990 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
289a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
289b0 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
289c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
289d0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
289e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
289f0 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
28a00 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
28a10 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
28a20 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
28a30 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
28a40 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
28a50 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
28a60 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
28a70 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
28a80 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
28a90 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
28aa0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
28ab0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
28ac0 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51  OLUMN]] ^(<dt>SQ
28ad0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
28ae0 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
28af0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
28b00 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
28b10 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
28b20 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
28b30 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
28b40 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
28b50 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
28b60 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
28b70 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
28b80 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
28b90 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
28ba0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
28bb0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
28bc0 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
28bd0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
28be0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
28bf0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
28c00 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
28c10 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
28c20 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
28c30 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
28c40 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
28c50 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ECT]] ^(<dt>SQLI
28c60 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
28c70 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
28c80 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
28c90 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
28ca0 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
28cb0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
28cc0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
28cd0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
28ce0 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  E_OP]] ^(<dt>SQL
28cf0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
28d00 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
28d10 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
28d20 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
28d30 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
28d40 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
28d50 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
28d60 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
28d70 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74  ent.  This limit
28d80 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
28d90 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74  y.** enforced, t
28da0 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74  hough that might
28db0 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d   be added in som
28dc0 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
28dd0 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f   of.** SQLite.</
28de0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
28df0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
28e00 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e  ION_ARG]] ^(<dt>
28e10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
28e20 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
28e30 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
28e40 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
28e50 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
28e60 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
28e70 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
28e80 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64  _ATTACHED]] ^(<d
28e90 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
28ea0 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
28eb0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
28ec0 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
28ed0 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
28ee0 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
28ef0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
28f00 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
28f10 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28  N_LENGTH]].** ^(
28f20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
28f30 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
28f40 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
28f50 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
28f60 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
28f70 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
28f80 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
28f90 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
28fa0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
28fb0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
28fc0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a  RIABLE_NUMBER]].
28fd0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
28fe0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
28ff0 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
29000 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e  d>The maximum in
29010 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e  dex number of an
29020 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  y [parameter] in
29030 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
29040 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  t.)^.**.** [[SQL
29050 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
29060 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
29070 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
29080 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
29090 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
290a0 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
290b0 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
290c0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
290d0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
290e0 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d  WORKER_THREADS]]
290f0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29100 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
29110 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  DS</dt>.** <dd>T
29120 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
29130 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77  r of auxiliary w
29140 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68  orker threads th
29150 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  at a single.** [
29160 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29170 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f  nt] may start.</
29180 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
29190 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
291a0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
291b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
291c0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
291d0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
291e0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
291f0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
29200 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
29210 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29220 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
29230 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
29240 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
29250 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
29260 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
29270 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
29280 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
29290 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
292a0 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
292b0 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
292c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
292d0 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
292e0 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
292f0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
29300 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
29310 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
29320 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
29330 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
29340 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
29350 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29360 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
29370 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
29380 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29390 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
293a0 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
293b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
293c0 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
293d0 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f             11../
293e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
293f0 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
29400 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
29410 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
29420 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
29430 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
29440 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f  e3.** CONSTRUCTO
29450 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  R: sqlite3_stmt.
29460 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
29470 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
29480 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
29490 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
294a0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
294b0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
294c0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
294d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
294e0 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
294f0 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
29500 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
29510 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
29520 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
29530 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
29540 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
29550 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
29560 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
29570 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
29580 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
29590 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
295a0 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
295b0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
295c0 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
295d0 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
295e0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
295f0 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
29600 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
29610 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
29620 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
29630 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
29640 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
29650 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
29660 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
29670 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
29680 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
29690 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
296a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
296b0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
296c0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
296d0 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
296e0 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
296f0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
29700 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70  . ^If nByte is p
29710 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74  ositive, then it
29720 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
29730 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20  r of bytes read 
29740 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20  from zSql.  ^If 
29750 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74  nByte is zero, t
29760 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a  hen no prepared.
29770 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ** statement is 
29780 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66  generated..** If
29790 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
297a0 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  s that the suppl
297b0 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
297c0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
297d0 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61  en.** there is a
297e0 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e   small performan
297f0 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
29800 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
29810 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
29820 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
29830 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
29840 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
29850 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
29860 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
29870 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ator..**.** ^If 
29880 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
29890 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
298a0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
298b0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
298c0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
298d0 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
298e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
298f0 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
29900 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
29910 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
29920 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
29930 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
29940 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
29950 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
29960 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
29970 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
29980 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
29990 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
299a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
299b0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
299c0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
299d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
299e0 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
299f0 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
29a00 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
29a10 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
29a20 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
29a30 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
29a40 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
29a50 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
29a60 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
29a70 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
29a80 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
29a90 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
29aa0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
29ab0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
29ac0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
29ad0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
29ae0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
29af0 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
29b00 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
29b10 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
29b20 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
29b30 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
29b40 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
29b50 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
29b60 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
29b70 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
29b80 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
29b90 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
29ba0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
29bb0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
29bc0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
29bd0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
29be0 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
29bf0 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
29c00 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
29c10 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
29c20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
29c30 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
29c40 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
29c50 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
29c60 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
29c70 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
29c80 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
29c90 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
29ca0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
29cb0 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
29cc0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
29cd0 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
29ce0 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
29cf0 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
29d00 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
29d10 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
29d20 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
29d30 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
29d40 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
29d50 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
29d60 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
29d70 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
29d80 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
29d90 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
29da0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
29db0 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
29dc0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
29dd0 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
29de0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
29df0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
29e00 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
29e10 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
29e20 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
29e30 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53  n. As many as [S
29e40 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41  QLITE_MAX_SCHEMA
29e50 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69  _RETRY].** retri
29e60 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65  es will occur be
29e70 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65  fore sqlite3_ste
29e80 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64  p() gives up and
29e90 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
29ea0 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  r..** </li>.**.*
29eb0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
29ec0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
29ed0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
29ee0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
29ef0 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
29f00 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
29f10 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
29f20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
29f30 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
29f40 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
29f50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
29f60 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
29f70 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
29f80 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
29f90 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
29fa0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
29fb0 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
29fc0 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
29fd0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
29fe0 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
29ff0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
2a000 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
2a010 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
2a020 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
2a030 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
2a040 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
2a050 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
2a060 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
2a070 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
2a080 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2a090 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
2a0a0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
2a0b0 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
2a0c0 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
2a0d0 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
2a0e0 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
2a0f0 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
2a100 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
2a110 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
2a120 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
2a130 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
2a140 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
2a150 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
2a160 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
2a170 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
2a180 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
2a190 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
2a1a0 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
2a1b0 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
2a1c0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
2a1d0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
2a1e0 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
2a1f0 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
2a200 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
2a210 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
2a220 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
2a230 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
2a240 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
2a250 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
2a260 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2a270 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
2a280 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
2a290 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
2a2a0 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
2a2b0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
2a2c0 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
2a2d0 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
2a2e0 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
2a2f0 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
2a300 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
2a310 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
2a320 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
2a330 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2a340 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
2a350 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2a360 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2a370 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2a380 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
2a390 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2a3a0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
2a3b0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2a3c0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2a3d0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2a3e0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2a3f0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2a400 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2a410 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2a420 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2a430 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2a440 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2a450 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2a460 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2a470 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2a480 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
2a490 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2a4a0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2a4b0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2a4c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
2a4d0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2a4e0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
2a4f0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2a500 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2a510 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2a520 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2a530 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2a540 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2a550 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2a560 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2a570 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2a580 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2a590 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2a5a0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2a5b0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2a5c0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2a5d0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
2a5e0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2a5f0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2a600 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2a610 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2a620 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2a630 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
2a640 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2a650 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2a660 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2a670 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2a680 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2a690 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2a6a0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2a6b0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2a6c0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
2a6d0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2a6e0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2a6f0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2a700 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2a710 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
2a720 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2a730 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2a740 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2a750 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2a760 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2a770 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2a780 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2a790 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2a7a0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2a7b0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2a7c0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2a7d0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2a7e0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2a7f0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2a800 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2a810 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2a820 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2a830 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2a840 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
2a850 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
2a860 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
2a870 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t SQL.** METHOD:
2a880 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2a890 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2a8a0 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63  _sql(P) interfac
2a8b0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2a8c0 74 65 72 20 74 6f 20 61 20 63 6f 70 79 20 6f 66  ter to a copy of
2a8d0 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51   the UTF-8.** SQ
2a8e0 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
2a8f0 72 65 61 74 65 20 5b 70 72 65 70 61 72 65 64 20  reate [prepared 
2a900 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 69 66 20  statement] P if 
2a910 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 74 65 64  P was.** created
2a920 20 62 79 20 65 69 74 68 65 72 20 5b 73 71 6c 69   by either [sqli
2a930 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2a940 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2a950 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
2a960 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
2a970 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69  xpanded_sql(P) i
2a980 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2a990 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2a9a0 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
2a9b0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53  containing the S
2a9c0 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70 61  QL text of prepa
2a9d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
2a9e0 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70  with.** [bound p
2a9f0 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e  arameters] expan
2aa00 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
2aa10 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70   example, if a p
2aa20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2aa30 74 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69  t is created usi
2aa40 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65  ng the SQL.** te
2aa50 78 74 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c  xt "SELECT $abc,
2aa60 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72  :xyz" and if par
2aa70 61 6d 65 74 65 72 20 24 61 62 63 20 69 73 20 62  ameter $abc is b
2aa80 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20  ound to integer 
2aa90 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61  2345.** and para
2aaa0 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e  meter :xyz is un
2aab0 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69  bound, then sqli
2aac0 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72  te3_sql() will r
2aad0 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69  eturn.** the ori
2aae0 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53  ginal string, "S
2aaf0 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22  ELECT $abc,:xyz"
2ab00 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70   but sqlite3_exp
2ab10 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77  anded_sql().** w
2ab20 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45  ill return "SELE
2ab30 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e  CT 2345,NULL".)^
2ab40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ab50 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2ab60 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2ab70 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73  urns NULL if ins
2ab80 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
2ab90 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65  .** is available
2aba0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
2abb0 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72  ult, or if the r
2abc0 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65  esult would exce
2abd0 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61  ed the.** the ma
2abe0 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e  ximum string len
2abf0 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62  gth determined b
2ac00 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49  y the [SQLITE_LI
2ac10 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a  MIT_LENGTH]..**.
2ac20 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
2ac30 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
2ac40 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2ac50 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65  ption limits the
2ac60 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e   size of.** boun
2ac70 64 20 70 61 72 61 6d 65 74 65 72 20 65 78 70 61  d parameter expa
2ac80 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53  nsions.  ^The [S
2ac90 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45  QLITE_OMIT_TRACE
2aca0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
2acb0 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20  * option causes 
2acc0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2acd0 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73  _sql() to always
2ace0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a   return NULL..**
2acf0 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20  .** ^The string 
2ad00 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2ad10 74 65 33 5f 73 71 6c 28 50 29 20 69 73 20 6d 61  te3_sql(P) is ma
2ad20 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74 65 20  naged by SQLite 
2ad30 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  and is.** automa
2ad40 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68  tically freed wh
2ad50 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 20  en the prepared 
2ad60 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e  statement is fin
2ad70 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  alized..** ^The 
2ad80 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20  string returned 
2ad90 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  by sqlite3_expan
2ada0 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74  ded_sql(P), on t
2adb0 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a  he other hand,.*
2adc0 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72  * is obtained fr
2add0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2ade0 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 62  oc()] and must b
2adf0 65 20 66 72 65 65 20 62 79 20 74 68 65 20 61 70  e free by the ap
2ae00 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20  plication.** by 
2ae10 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
2ae20 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2ae30 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2ae40 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
2ae50 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2ae60 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65  .char *sqlite3_e
2ae70 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69  xpanded_sql(sqli
2ae80 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2ae90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2aea0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2aeb0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2aec0 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
2aed0 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  base.** METHOD: 
2aee0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2aef0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2af00 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
2af10 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2af20 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
2af30 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
2af40 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
2af50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
2af60 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
2af70 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
2af80 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2af90 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
2afa0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2afb0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2afc0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2afd0 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
2afe0 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
2aff0 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2b000 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
2b010 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
2b020 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
2b030 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
2b040 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
2b050 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
2b060 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
2b070 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
2b080 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
2b090 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
2b0a0 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
2b0b0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2b0c0 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
2b0d0 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
2b0e0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2b0f0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
2b100 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
2b110 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
2b120 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
2b130 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
2b140 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
2b150 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2b160 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
2b170 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2b180 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
2b190 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
2b1a0 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
2b1b0 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
2b1c0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
2b1d0 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
2b1e0 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
2b1f0 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
2b200 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
2b210 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
2b220 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
2b230 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
2b240 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
2b250 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
2b260 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
2b270 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
2b280 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
2b290 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
2b2a0 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
2b2b0 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
2b2c0 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
2b2d0 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
2b2e0 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
2b2f0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
2b300 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
2b310 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
2b320 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
2b330 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
2b340 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
2b350 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
2b360 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
2b370 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
2b380 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
2b390 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
2b3a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
2b3b0 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
2b3c0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
2b3d0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2b3e0 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
2b3f0 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73  n disk..*/.int s
2b400 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2b410 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  only(sqlite3_stm
2b420 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2b430 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
2b440 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61  rmine If A Prepa
2b450 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61  red Statement Ha
2b460 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20  s Been Reset.** 
2b470 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2b480 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2b490 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2b4a0 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(S) interface r
2b4b0 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
2b4c0 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a  -zero) if the.**
2b4d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b4e0 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e  ment] S has been
2b4f0 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73   stepped at leas
2b500 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a  t once using .**
2b510 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2b520 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74 68  )] but has neith
2b530 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65  er run to comple
2b540 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a  tion (returned.*
2b550 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20  * [SQLITE_DONE] 
2b560 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74  from [sqlite3_st
2b570 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62  ep(S)]) nor.** b
2b580 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20  een reset using 
2b590 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2b5a0 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  )].  ^The sqlite
2b5b0 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a  3_stmt_busy(S).*
2b5c0 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
2b5d0 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69  rns false if S i
2b5e0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2b5f0 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61  .  If S is not a
2b600 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   .** NULL pointe
2b610 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  r and is not a p
2b620 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69  ointer to a vali
2b630 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
2b640 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
2b650 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2b660 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2b670 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
2b680 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  desirable..**.**
2b690 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
2b6a0 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63  can be used in c
2b6b0 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69  ombination [sqli
2b6c0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d  te3_next_stmt()]
2b6d0 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c  .** to locate al
2b6e0 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  l prepared state
2b6f0 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64  ments associated
2b700 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65   with a database
2b710 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   .** connection 
2b720 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64  that are in need
2b730 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e   of being reset.
2b740 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73    This can be us
2b750 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70  ed,.** for examp
2b760 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69  le, in diagnosti
2b770 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65  c routines to se
2b780 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65  arch for prepare
2b790 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  d .** statements
2b7a0 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e   that are holdin
2b7b0 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  g a transaction 
2b7c0 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  open..*/.int sql
2b7d0 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
2b7e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2b7f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b800 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
2b810 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
2b820 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
2b830 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b840 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
2b850 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2b860 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
2b870 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
2b880 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
2b890 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
2b8a0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
2b8b0 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
2b8c0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
2b8d0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
2b8e0 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
2b8f0 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
2b900 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
2b910 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
2b920 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2b930 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
2b940 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
2b950 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
2b960 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
2b970 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
2b980 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2b990 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
2b9a0 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
2b9b0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
2b9c0 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
2b9d0 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
2b9e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2b9f0 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
2ba00 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
2ba10 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
2ba20 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
2ba30 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2ba40 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
2ba50 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
2ba60 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
2ba70 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
2ba80 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
2ba90 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
2baa0 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
2bab0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2bac0 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  lue.  The.** [sq
2bad0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
2bae0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  )] interface can
2baf0 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73   be used to cons
2bb00 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20  truct a new .** 
2bb10 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2bb20 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20  3_value from an 
2bb30 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2bb40 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
2bb50 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
2bb60 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
2bb70 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
2bb80 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
2bb90 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
2bba0 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
2bbb0 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
2bbc0 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
2bbd0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2bbe0 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
2bbf0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
2bc00 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
2bc10 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2bc20 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
2bc30 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
2bc40 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
2bc50 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
2bc60 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
2bc70 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
2bc80 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2bc90 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
2bca0 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
2bcb0 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
2bcc0 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
2bcd0 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
2bce0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2bcf0 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
2bd00 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
2bd10 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
2bd20 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
2bd30 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
2bd40 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
2bd50 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2bd60 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2bd70 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
2bd80 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
2bd90 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
2bda0 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
2bdb0 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
2bdc0 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
2bdd0 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
2bde0 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
2bdf0 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
2be00 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
2be10 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
2be20 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2be30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
2be40 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
2be50 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
2be60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2be70 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2be80 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
2be90 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
2bea0 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
2beb0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
2bec0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2bed0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2bee0 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
2bef0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2bf00 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
2bf10 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2bf20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2bf30 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
2bf40 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
2bf50 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2bf60 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
2bf70 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
2bf80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
2bf90 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
2bfa0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2bfb0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
2bfc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2bfd0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
2bfe0 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
2bff0 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
2c000 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
2c010 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c020 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
2c030 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
2c040 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
2c050 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c060 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
2c070 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
2c080 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
2c090 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
2c0a0 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
2c0b0 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
2c0c0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
2c0d0 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
2c0e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
2c0f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
2c100 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
2c110 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
2c120 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
2c130 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2c140 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
2c150 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2c160 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2c170 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2c180 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
2c190 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
2c1a0 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
2c1b0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
2c1c0 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
2c1d0 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
2c1e0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2c1f0 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
2c200 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2c210 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2c220 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
2c230 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
2c240 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
2c250 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
2c260 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
2c270 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2c280 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
2c290 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
2c2a0 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
2c2b0 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
2c2c0 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
2c2d0 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
2c2e0 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
2c2f0 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
2c300 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
2c310 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2c320 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2c330 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
2c340 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
2c350 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
2c360 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ng}.** METHOD: s
2c370 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2c380 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
2c390 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
2c3a0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
2c3b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2c3c0 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
2c3d0 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
2c3e0 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
2c3f0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
2c400 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
2c410 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
2c420 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
2c430 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
2c440 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
2c450 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
2c460 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
2c470 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
2c480 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
2c490 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
2c4a0 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
2c4b0 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
2c4c0 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
2c4d0 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
2c4e0 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
2c4f0 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
2c500 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
2c510 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
2c520 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
2c530 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
2c540 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
2c550 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
2c560 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
2c570 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2c580 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
2c590 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2c5a0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2c5b0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2c5c0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
2c5d0 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
2c5e0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
2c5f0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
2c600 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
2c610 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2c620 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
2c630 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
2c640 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
2c650 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
2c660 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
2c670 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
2c680 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
2c690 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
2c6a0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2c6b0 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
2c6c0 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
2c6d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
2c6e0 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
2c6f0 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
2c700 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
2c710 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
2c720 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
2c730 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
2c740 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
2c750 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
2c760 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
2c770 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
2c780 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
2c790 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2c7a0 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
2c7b0 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
2c7c0 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
2c7d0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
2c7e0 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
2c7f0 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
2c800 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
2c810 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
2c820 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
2c830 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
2c840 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2c850 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
2c860 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
2c870 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
2c880 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2c890 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
2c8a0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2c8b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
2c8c0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2c8d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2c8e0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
2c8f0 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
2c900 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2c910 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c  blob() is a NULL
2c920 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
2c930 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2c940 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64  er.** is ignored
2c950 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73   and the end res
2c960 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20  ult is the same 
2c970 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  as sqlite3_bind_
2c980 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  null()..**.** ^(
2c990 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
2c9a0 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
2c9b0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
2c9c0 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
2c9d0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
2c9e0 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
2c9f0 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
2ca00 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
2ca10 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2ca20 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
2ca30 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
2ca40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
2ca50 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
2ca60 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
2ca70 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2ca80 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
2ca90 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2caa0 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65  ext16().** is ne
2cab0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
2cac0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
2cad0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
2cae0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2caf0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
2cb00 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2cb10 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
2cb20 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2cb30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2cb40 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  () is negative, 
2cb50 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61  then.** the beha
2cb60 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2cb70 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e  d..** If a non-n
2cb80 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70  egative fourth p
2cb90 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76  arameter is prov
2cba0 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ided to sqlite3_
2cbb0 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f  bind_text().** o
2cbc0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2cbd0 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74  ext16() or sqlit
2cbe0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2cbf0 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61   then.** that pa
2cc00 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
2cc10 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a  the byte offset.
2cc20 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ** where the NUL
2cc30 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
2cc40 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67  d occur assuming
2cc50 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65   the string were
2cc60 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74   NUL.** terminat
2cc70 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
2cc80 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
2cc90 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73   at byte offsets
2cca0 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74   less than .** t
2ccb0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2ccc0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2ccd0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2cce0 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65  ing string value
2ccf0 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e   will.** contain
2cd00 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20   embedded NULs. 
2cd10 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65   The result of e
2cd20 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c  xpressions invol
2cd30 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20  ving strings.** 
2cd40 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
2cd50 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
2cd60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
2cd70 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
2cd80 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e  e BLOB and strin
2cd90 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66  g binding interf
2cda0 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73  aces.** is a des
2cdb0 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
2cdc0 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
2cdd0 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
2cde0 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
2cdf0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2ce00 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  it.  ^The destru
2ce10 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a  ctor is called.*
2ce20 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  * to dispose of 
2ce30 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
2ce40 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63  ng even if the c
2ce50 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20  all to bind API 
2ce60 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  fails..** ^If th
2ce70 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2ce80 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
2ce90 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
2cea0 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
2ceb0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
2cec0 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
2ced0 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
2cee0 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
2cef0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
2cf00 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
2cf10 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
2cf20 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
2cf30 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
2cf40 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
2cf50 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
2cf60 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
2cf70 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
2cf80 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
2cf90 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
2cfa0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2cfb0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2cfc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ..**.** ^The six
2cfd0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2cfe0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2cff0 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  64() must be one
2d000 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   of.** [SQLITE_U
2d010 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
2d020 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  F16], [SQLITE_UT
2d030 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49  F16BE], or [SQLI
2d040 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74  TE_UTF16LE].** t
2d050 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e  o specify the en
2d060 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65  coding of the te
2d070 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  xt in the third 
2d080 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a  parameter.  If.*
2d090 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75  * the sixth argu
2d0a0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2d0b0 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73  bind_text64() is
2d0c0 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
2d0d0 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65  ** allowed value
2d0e0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f  s shown above, o
2d0f0 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e  r if the text en
2d100 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
2d110 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ent.** from the 
2d120 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
2d130 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20  ed by the sixth 
2d140 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
2d150 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
2d160 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2d170 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2d180 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
2d190 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
2d1a0 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
2d1b0 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
2d1c0 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
2d1d0 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
2d1e0 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
2d1f0 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
2d200 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
2d210 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
2d220 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
2d230 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
2d240 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
2d250 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
2d260 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
2d270 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
2d280 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
2d290 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
2d2a0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2d2b0 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
2d2c0 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
2d2d0 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
2d2e0 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
2d2f0 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
2d300 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
2d310 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
2d320 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
2d330 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
2d340 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2d350 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
2d360 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2d370 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
2d380 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
2d390 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
2d3a0 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
2d3b0 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
2d3c0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
2d3d0 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
2d3e0 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
2d3f0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
2d400 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
2d410 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
2d420 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
2d430 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
2d440 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
2d450 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
2d460 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d470 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
2d480 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
2d490 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
2d4a0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
2d4b0 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
2d4c0 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
2d4d0 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
2d4e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2d4f0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
2d500 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
2d510 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
2d520 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
2d530 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2d540 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
2d550 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2d560 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
2d570 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
2d580 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
2d590 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
2d5a0 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d  ^[SQLITE_TOOBIG]
2d5b0 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2d5c0 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  ed if the size o
2d5d0 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  f a string or BL
2d5e0 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69  OB.** exceeds li
2d5f0 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20  mits imposed by 
2d600 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
2d610 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2d620 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51  NGTH]) or.** [SQ
2d630 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d  LITE_MAX_LENGTH]
2d640 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
2d650 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
2d660 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2d670 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
2d680 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
2d690 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
2d6a0 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
2d6b0 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
2d6c0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2d6d0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2d6e0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
2d6f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2d700 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2d710 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
2d720 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2d730 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
2d740 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2d750 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d760 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2d770 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
2d780 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2d790 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36  lite3_bind_blob6
2d7a0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2d7b0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2d7c0 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
2d7d0 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
2d7e0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
2d7f0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2d800 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
2d810 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
2d820 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
2d830 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2d840 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
2d850 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
2d860 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2d870 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2d880 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
2d890 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
2d8a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2d8b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d8c0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
2d8d0 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
2d8e0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f  te3_stmt*,int,co
2d8f0 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f  nst char*,int,vo
2d900 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2d910 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2d920 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2d930 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2d940 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2d950 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2d960 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2d970 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  ext64(sqlite3_st
2d980 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2d990 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75  char*, sqlite3_u
2d9a0 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
2d9b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d9c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20  void(*)(void*), 
2d9d0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e  unsigned char en
2d9e0 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c  coding);.int sql
2d9f0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2da00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2da10 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
2da20 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2da30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2da40 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2da50 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
2da60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2da70 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c  d_zeroblob64(sql
2da80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2da90 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29   sqlite3_uint64)
2daa0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2dab0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
2dac0 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d   Parameters.** M
2dad0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2dae0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  tmt.**.** ^This 
2daf0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
2db00 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
2db10 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
2db20 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
2db30 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2db40 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
2db50 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
2db60 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
2db70 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
2db80 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
2db90 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
2dba0 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
2dbb0 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
2dbc0 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
2dbd0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2dbe0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
2dbf0 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
2dc00 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
2dc10 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
2dc20 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
2dc30 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
2dc40 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
2dc50 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
2dc60 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
2dc70 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
2dc80 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
2dc90 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
2dca0 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
2dcb0 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
2dcc0 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
2dcd0 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
2dce0 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
2dcf0 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
2dd00 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
2dd10 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2dd20 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2dd30 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2dd40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2dd50 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2dd60 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2dd70 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2dd80 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2dd90 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2dda0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2ddb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2ddc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ddd0 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
2dde0 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45   Parameter.** ME
2ddf0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2de00 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2de10 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2de20 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
2de30 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2de40 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
2de50 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
2de60 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
2de70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2de80 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
2de90 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
2dea0 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
2deb0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
2dec0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
2ded0 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
2dee0 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
2def0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
2df00 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
2df10 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
2df20 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
2df30 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
2df40 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
2df50 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
2df60 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
2df70 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
2df80 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
2df90 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
2dfa0 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
2dfb0 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
2dfc0 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
2dfd0 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
2dfe0 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
2dff0 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
2e000 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
2e010 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
2e020 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
2e030 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
2e040 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
2e050 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
2e060 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
2e070 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
2e080 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
2e090 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
2e0a0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
2e0b0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2e0c0 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
2e0d0 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
2e0e0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
2e0f0 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
2e100 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
2e110 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
2e120 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
2e130 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
2e140 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2e150 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
2e160 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2e170 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2e180 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2e190 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2e1a0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2e1b0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2e1c0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2e1d0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2e1e0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2e1f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2e200 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
2e210 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
2e220 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
2e230 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
2e240 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
2e250 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Name.** METHOD:
2e260 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2e270 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2e280 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
2e290 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
2e2a0 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
2e2b0 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
2e2c0 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
2e2d0 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
2e2e0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
2e2f0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2e300 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2e310 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
2e320 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
2e330 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
2e340 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
2e350 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
2e360 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
2e370 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
2e380 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
2e390 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
2e3a0 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
2e3b0 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
2e3c0 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
2e3d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2e3e0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
2e3f0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2e400 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2e410 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
2e420 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2e430 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2e440 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2e450 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e460 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  name()]..*/.int 
2e470 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2e480 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
2e490 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
2e4a0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
2e4b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e4c0 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
2e4d0 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
2e4e0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d  d Statement.** M
2e4f0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2e500 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72  tmt.**.** ^Contr
2e510 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
2e520 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
2e530 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2e540 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
2e550 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
2e560 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
2e570 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
2e580 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2e590 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75  ** ^Use this rou
2e5a0 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
2e5b0 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
2e5c0 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  s to NULL..*/.in
2e5d0 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
2e5e0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
2e5f0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2e600 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2e610 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
2e620 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d   Result Set.** M
2e630 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2e640 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  tmt.**.** ^Retur
2e650 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
2e660 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2e670 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
2e680 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
2e690 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e6a0 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ]. ^This routine
2e6b0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
2e6c0 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
2e6d0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
2e6e0 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
2e6f0 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
2e700 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
2e710 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2e720 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
2e730 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
2e740 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2e750 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2e760 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2e770 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
2e780 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
2e790 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt Set.** METHOD
2e7a0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2e7b0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2e7c0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2e7d0 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
2e7e0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
2e7f0 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
2e800 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
2e810 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2e820 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  t.  ^The sqlite3
2e830 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
2e840 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
2e850 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2e860 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2e870 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
2e880 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
2e890 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
2e8a0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2e8b0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
2e8c0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
2e8d0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69  string.  ^The fi
2e8e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2e8f0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2e900 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
2e910 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
2e920 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2e930 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ent. ^The second
2e940 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2e950 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
2e960 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f  er.  ^The leftmo
2e970 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
2e980 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ber 0..**.** ^Th
2e990 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2e9a0 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
2e9b0 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
2e9c0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2e9d0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
2e9e0 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
2e9f0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2ea00 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
2ea10 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
2ea20 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
2ea30 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
2ea40 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
2ea50 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
2ea60 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
2ea70 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
2ea80 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
2ea90 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2eaa0 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
2eab0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2eac0 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
2ead0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
2eae0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
2eaf0 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
2eb00 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
2eb10 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
2eb20 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
2eb30 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
2eb40 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
2eb50 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
2eb60 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
2eb70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2eb80 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
2eb90 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
2eba0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
2ebb0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
2ebc0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
2ebd0 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
2ebe0 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
2ebf0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
2ec00 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
2ec10 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2ec20 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
2ec30 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
2ec40 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
2ec50 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
2ec60 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
2ec70 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2ec80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2ec90 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2eca0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
2ecb0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2ecc0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
2ecd0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2ece0 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
2ecf0 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
2ed00 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
2ed10 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  esult.** METHOD:
2ed20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2ed30 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2ed40 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
2ed50 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
2ed60 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74   the database, t
2ed70 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62  able, and.** tab
2ed80 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  le column that i
2ed90 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20  s the origin of 
2eda0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73  a particular res
2edb0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a  ult column in.**
2edc0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2edd0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ent..** ^The nam
2ede0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
2edf0 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
2ee00 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
2ee10 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
2ee20 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
2ee30 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
2ee40 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
2ee50 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
2ee60 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
2ee70 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
2ee80 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2ee90 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
2eea0 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
2eeb0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2eec0 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
2eed0 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
2eee0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
2eef0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
2ef00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ef10 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
2ef20 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
2ef30 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2ef40 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2ef50 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2ef60 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2ef70 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2ef80 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2ef90 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2efa0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2efb0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  * or until the s
2efc0 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
2efd0 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
2efe0 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
2eff0 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
2f000 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20  *.** ^The names 
2f010 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
2f020 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
2f030 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
2f040 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
2f050 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
2f060 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2f070 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2f080 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
2f090 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2f0a0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54  tatement]..** ^T
2f0b0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2f0c0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2f0d0 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
2f0e0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65  result column re
2f0f0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
2f100 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
2f110 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
2f120 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
2f130 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  ent..** ^The lef
2f140 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
2f150 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68   column 0 for th
2f160 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
2f170 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20  .** ^If the Nth 
2f180 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
2f190 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
2f1a0 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
2f1b0 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
2f1c0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
2f1d0 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
2f1e0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
2f1f0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
2f200 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20  * NULL.  ^These 
2f210 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
2f220 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
2f230 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2f240 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
2f250 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69  ccurs.  ^Otherwi
2f260 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
2f270 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2f280 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2f290 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20  e, table,.** or 
2f2a0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
2f2b0 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
2f2c0 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
2f2d0 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69  om..**.** ^As wi
2f2e0 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
2f2f0 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
2f300 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20  whose names end 
2f310 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
2f320 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
2f330 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74  ed strings and t
2f340 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
2f350 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
2f360 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50  .**.** ^These AP
2f370 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
2f380 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
2f390 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
2f3a0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
2f3b0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
2f3c0 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
2f3d0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
2f3e0 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  bol..**.** If tw
2f3f0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
2f400 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
2f410 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
2f420 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
2f430 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
2f440 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
2f450 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
2f460 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
2f470 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
2f480 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2f490 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2f4a0 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2f4b0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
2f4c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2f4d0 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
2f4e0 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
2f4f0 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
2f500 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
2f510 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
2f520 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
2f530 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
2f540 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2f550 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2f560 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
2f570 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2f580 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73  _database_name(s
2f590 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2f5a0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2f5b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2f5c0 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71  tabase_name16(sq
2f5d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2f5e0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
2f5f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
2f600 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  le_name(sqlite3_
2f610 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2f620 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2f630 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
2f640 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2f650 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
2f660 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2f670 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
2f680 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2f690 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2f6a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
2f6b0 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
2f6c0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2f6d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f6e0 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
2f6f0 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
2f700 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  sult.** METHOD: 
2f710 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2f720 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
2f730 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
2f740 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f750 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
2f760 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
2f770 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2f780 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
2f790 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
2f7a0 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
2f7b0 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
2f7c0 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
2f7d0 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
2f7e0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2f7f0 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
2f800 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
2f810 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
2f820 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
2f830 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
2f840 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
2f850 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
2f860 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2f870 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
2f880 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2f890 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
2f8a0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2f8b0 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
2f8c0 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
2f8d0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
2f8e0 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
2f8f0 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
2f900 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
2f910 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
2f920 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
2f930 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
2f940 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
2f950 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
2f960 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
2f970 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
2f980 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
2f990 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
2f9a0 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
2f9b0 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
2f9c0 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
2f9d0 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
2f9e0 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
2f9f0 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
2fa00 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
2fa10 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
2fa20 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
2fa30 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
2fa40 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
2fa50 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
2fa60 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
2fa70 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
2fa80 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
2fa90 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
2faa0 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
2fab0 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
2fac0 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
2fad0 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
2fae0 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
2faf0 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
2fb00 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
2fb10 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
2fb20 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
2fb30 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
2fb40 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
2fb50 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
2fb60 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
2fb70 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ues..*/.const ch
2fb80 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2fb90 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
2fba0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2fbb0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2fbc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2fbd0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
2fbe0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2fbf0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
2fc00 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
2fc10 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
2fc20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2fc30 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
2fc40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2fc50 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
2fc60 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
2fc70 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2fc80 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
2fc90 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2fca0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
2fcb0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
2fcc0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
2fcd0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
2fce0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2fcf0 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
2fd00 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
2fd10 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
2fd20 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
2fd30 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
2fd40 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
2fd50 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
2fd60 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
2fd70 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
2fd80 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
2fd90 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
2fda0 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
2fdb0 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
2fdc0 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
2fdd0 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
2fde0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2fdf0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2fe00 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
2fe10 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
2fe20 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
2fe30 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2fe40 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2fe50 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
2fe60 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
2fe70 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
2fe80 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
2fe90 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
2fea0 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
2feb0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2fec0 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
2fed0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
2fee0 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65  **.** ^In the le
2fef0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2ff00 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2ff10 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
2ff20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
2ff30 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
2ff40 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
2ff50 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
2ff60 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
2ff70 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
2ff80 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
2ff90 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
2ffa0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
2ffb0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
2ffc0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
2ffd0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
2ffe0 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  as well..**.** ^
2fff0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
30000 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
30010 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
30020 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
30030 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
30040 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
30050 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
30060 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d    ^If the statem
30070 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
30080 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
30090 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
300a0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
300b0 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
300c0 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
300d0 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
300e0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
300f0 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
30100 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e  occurs within an
30110 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
30120 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
30130 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
30140 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
30150 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
30160 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  inuing..**.** ^[
30170 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
30180 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
30190 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
301a0 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
301b0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
301c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
301d0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
301e0 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
301f0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
30200 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
30210 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
30220 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
30230 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
30240 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
30250 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
30260 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  state..**.** ^If
30270 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
30280 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
30290 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
302a0 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
302b0 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
302c0 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
302d0 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
302e0 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
302f0 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
30300 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
30310 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
30320 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
30330 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
30340 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
30350 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
30360 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
30370 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
30380 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
30390 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52  *.** ^[SQLITE_ER
303a0 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
303b0 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
303c0 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
303d0 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
303e0 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
303f0 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
30400 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
30410 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
30420 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
30430 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
30440 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
30450 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
30460 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74  rmsg()]..** ^Wit
30470 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
30480 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
30490 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
304a0 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
304b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
304c0 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
304d0 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
304e0 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
304f0 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
30500 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
30510 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
30520 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
30530 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
30540 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68  tement].  ^In th
30550 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
30560 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
30570 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
30580 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
30590 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
305a0 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
305b0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
305c0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
305d0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
305e0 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
305f0 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
30600 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
30610 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
30620 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
30630 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
30640 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
30650 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
30660 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
30670 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
30680 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
30690 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
306a0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
306b0 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
306c0 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
306d0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
306e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
306f0 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
30700 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
30710 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
30720 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
30730 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65  **.** For all ve
30740 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
30750 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75   up to and inclu
30760 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61  ding 3.6.23.1, a
30770 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
30780 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61  ite3_reset()] wa
30790 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72  s required after
307a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
307b0 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
307c0 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  g.** other than 
307d0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66  [SQLITE_ROW] bef
307e0 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65  ore any subseque
307f0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  nt invocation of
30800 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
30810 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20  ().  Failure to 
30820 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
30830 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
30840 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
30850 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72  reset()] would r
30860 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
30870 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
30880 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  rn from.** sqlit
30890 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20  e3_step().  But 
308a0 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e  after version 3.
308b0 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f  6.23.1, sqlite3_
308c0 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20  step() began.** 
308d0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
308e0 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61  _reset()] automa
308f0 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20  tically in this 
30900 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74  circumstance rat
30910 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75  her.** than retu
30920 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49  rning [SQLITE_MI
30930 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20  SUSE].  This is 
30940 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61  not considered a
30950 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a   compatibility.*
30960 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20  * break because 
30970 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  any application 
30980 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76  that ever receiv
30990 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53  es an SQLITE_MIS
309a0 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20  USE error.** is 
309b0 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69  broken by defini
309c0 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49  tion.  The [SQLI
309d0 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45  TE_OMIT_AUTORESE
309e0 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
309f0 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65  option.** can be
30a00 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65   used to restore
30a10 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   the legacy beha
30a20 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  vior..**.** <b>G
30a30 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
30a40 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65  lert:</b> In the
30a50 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
30a60 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  e, the sqlite3_s
30a70 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77  tep().** API alw
30a80 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
30a90 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
30aa0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
30ab0 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a  , following any.
30ac0 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ** error other t
30ad0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
30ae0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  ] and [SQLITE_MI
30af0 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
30b00 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
30b10 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
30b20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
30b30 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
30b40 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ind one of the.*
30b50 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  * specific [erro
30b60 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  r codes] that be
30b70 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
30b80 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
30b90 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
30ba0 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
30bb0 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
30bc0 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
30bd0 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
30be0 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
30bf0 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
30c00 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
30c10 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
30c20 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
30c30 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
30c40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
30c50 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
30c60 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
30c70 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
30c80 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
30c90 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
30ca0 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
30cb0 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
30cc0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
30cd0 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
30ce0 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
30cf0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
30d00 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
30d10 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
30d20 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
30d30 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
30d40 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
30d50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30d60 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
30d70 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
30d80 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t set.** METHOD:
30d90 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30da0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30db0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
30dc0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
30dd0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
30de0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
30df0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
30e00 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
30e10 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
30e20 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
30e30 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
30e40 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
30e50 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
30e60 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
30e70 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
30e80 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
30e90 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
30ea0 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
30eb0 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
30ec0 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
30ed0 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
30ee0 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
30ef0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
30f00 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
30f10 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
30f20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
30f30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30f40 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
30f50 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
30f60 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  if the previous 
30f70 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
30f80 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
30f90 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f  urned [SQLITE_DO
30fa0 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  NE].  ^The sqlit
30fb0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
30fc0 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
30fd0 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76  non-zero if prev
30fe0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ious call to [sq
30ff0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
31000 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
31010 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20  TE_ROW], except 
31020 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74  in the case of t
31030 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65  he [PRAGMA incre
31040 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a  mental_vacuum].*
31050 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79  * where it alway
31060 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73  s returns zero s
31070 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f  ince each step o
31080 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65  f that multi-ste
31090 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75  p.** pragma retu
310a0 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66  rns 0 columns of
310b0 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   data..**.** See
310c0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
310d0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
310e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
310f0 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
31100 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
31110 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31120 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
31130 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
31140 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
31150 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
31160 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
31170 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
31180 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
31190 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
311a0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
311b0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
311c0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
311d0 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
311e0 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
311f0 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
31200 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
31210 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
31220 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
31230 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
31240 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
31250 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
31260 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
31270 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
31280 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
31290 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
312a0 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
312b0 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
312c0 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
312d0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
312e0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
312f0 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
31300 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
31310 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
31320 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
31330 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
31340 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
31350 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
31360 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
31370 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
31380 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
31390 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
313a0 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
313b0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
313c0 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
313d0 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
313e0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
313f0 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
31400 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
31410 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
31420 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
31430 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
31440 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
31450 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
31460 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44  tions}.** METHOD
31470 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
31480 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
31490 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
314a0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
314b0 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
314c0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
314d0 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
314e0 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
314f0 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
31500 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
31510 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
31520 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31530 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
31540 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
31550 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
31560 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
31570 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
31580 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
31590 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
315a0 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
315b0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
315c0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
315d0 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
315e0 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
315f0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
31600 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
31610 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
31620 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
31630 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
31640 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
31650 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
31660 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
31670 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
31680 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
31690 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
316a0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
316b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
316c0 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
316d0 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
316e0 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
316f0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
31700 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
31710 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
31720 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
31730 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
31740 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
31750 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
31760 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
31770 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
31780 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
31790 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
317a0 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
317b0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
317c0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
317d0 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
317e0 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
317f0 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
31800 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
31810 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
31820 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
31830 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
31840 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
31850 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
31860 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
31870 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
31880 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
31890 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
318a0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
318b0 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
318c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
318d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
318e0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
318f0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
31900 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
31910 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
31920 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
31930 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
31940 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
31950 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
31960 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
31970 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31980 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
31990 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
319a0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
319b0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
319c0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
319d0 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
319e0 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
319f0 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
31a00 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
31a10 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
31a20 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
31a30 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
31a40 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
31a50 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
31a60 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
31a70 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
31a80 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
31a90 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
31aa0 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
31ab0 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
31ac0 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
31ad0 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
31ae0 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
31af0 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
31b00 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
31b10 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
31b20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
31b30 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
31b40 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
31b50 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
31b60 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
31b70 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
31b80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
31b90 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
31ba0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
31bb0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
31bc0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
31bd0 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
31be0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
31bf0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
31c00 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
31c10 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
31c20 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
31c30 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
31c40 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
31c50 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
31c60 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
31c70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
31c80 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
31c90 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
31ca0 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
31cb0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
31cc0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
31cd0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
31ce0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
31cf0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
31d00 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
31d10 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
31d20 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
31d30 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
31d40 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
31d50 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
31d60 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
31d70 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
31d80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
31d90 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
31da0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31db0 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20  bytes() returns 
31dc0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  zero..**.** ^If 
31dd0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
31de0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73  BLOB or UTF-16 s
31df0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
31e00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31e10 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  tes16().** routi
31e20 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
31e30 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
31e40 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
31e50 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
31e60 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
31e70 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  F-8 string, then
31e80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31e90 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72  bytes16() conver
31ea0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
31eb0 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74   to UTF-16 and t
31ec0 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
31ed0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
31ee0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
31ef0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
31f00 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
31f10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
31f20 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  6() uses.** [sql
31f30 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
31f40 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
31f50 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
31f60 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  16 string and re
31f70 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
31f80 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
31f90 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
31fa0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
31fb0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
31fc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31fd0 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65  s16() returns ze
31fe0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76  ro..**.** ^The v
31ff0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
32000 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
32010 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a  n_bytes()] and .
32020 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
32030 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f  mn_bytes16()] do
32040 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
32050 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
32060 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  s at the end.** 
32070 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
32080 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68  ^For clarity: th
32090 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
320a0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
320b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
320c0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
320d0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
320e0 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  are the number o
320f0 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
32100 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
32110 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
32120 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53  acters..**.** ^S
32130 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
32140 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
32150 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
32160 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
32170 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
32180 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
32190 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
321a0 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72  minated.  ^The r
321b0 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
321c0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
321d0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
321e0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
321f0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
32200 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72  er..**.** <b>War
32210 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f  ning:</b> ^The o
32220 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
32230 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
32240 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
32250 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
32260 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
32270 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75  object.  In a mu
32280 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e 76 69  ltithreaded envi
32290 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75  ronment,.** an u
322a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
322b0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
322c0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
322d0 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20   safely with.** 
322e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
322f0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
32300 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
32310 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
32320 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
32330 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32340 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
32350 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
32360 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
32370 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
32380 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
32390 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
323a0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
323b0 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
323c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
323d0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
323e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
323f0 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69  s()], the behavi
32400 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  or is not thread
32410 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  safe..**.** Thes
32420 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
32430 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
32440 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
32450 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
32460 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
32470 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
32480 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
32490 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
324a0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
324b0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
324c0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
324d0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
324e0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
324f0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
32500 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
32510 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
32520 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
32530 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
32540 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
32550 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
32560 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
32570 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
32580 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
32590 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
325a0 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
325b0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
325c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
325d0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
325e0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
325f0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
32600 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
32610 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
32620 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
32630 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
32640 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
32650 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
32660 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
32670 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
32680 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
32690 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
326a0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
326b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
326c0 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
326d0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
326e0 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
326f0 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
32700 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
32710 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
32720 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
32730 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
32740 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
32750 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
32760 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
32770 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
32780 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
32790 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
327a0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
327b0 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
327c0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
327d0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
327e0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
327f0 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
32800 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
32810 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
32820 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
32830 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c  to BLOB.** <tr><
32840 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
32850 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
32860 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
32870 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
32880 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
32890 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
328a0 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
328b0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
328c0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
328d0 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
328e0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
328f0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
32900 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
32910 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
32920 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
32930 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
32940 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
32950 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
32960 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
32970 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
32980 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
32990 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
329a0 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
329b0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e  quote>)^.**.** N
329c0 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
329d0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
329e0 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
329f0 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
32a00 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
32a10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
32a20 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
32a30 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
32a40 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
32a50 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
32a60 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
32a70 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
32a80 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
32a90 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
32aa0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
32ab0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
32ac0 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
32ad0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
32ae0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
32af0 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
32b00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
32b10 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
32b20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
32b30 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
32b40 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
32b50 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
32b60 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
32b70 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
32b80 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
32b90 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
32ba0 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
32bb0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
32bc0 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
32bd0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
32be0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
32bf0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
32c00 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
32c10 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
32c20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
32c30 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
32c40 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
32c50 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
32c60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32c70 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
32c80 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
32c90 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
32ca0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
32cb0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
32cc0 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
32cd0 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
32ce0 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73  >.**.** ^Convers
32cf0 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
32d00 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
32d10 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
32d20 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
32d30 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
32d40 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
32d50 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
32d60 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
32d70 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
32d80 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
32d90 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72  or pointer refer
32da0 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20  ences will have 
32db0 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
32dc0 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
32dd0 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
32de0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
32df0 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
32e00 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
32e10 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
32e20 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
32e30 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
32e40 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
32e50 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
32e60 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 70  .** The safest p
32e70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
32e80 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
32e90 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
32ea0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
32eb0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
32ec0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
32ed0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
32ee0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
32ef0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
32f00 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
32f10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
32f20 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
32f30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32f40 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
32f50 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
32f60 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
32f70 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
32f80 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
32f90 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
32fa0 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
32fb0 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
32fc0 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
32fd0 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
32fe0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
32ff0 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
33000 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
33010 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
33020 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
33030 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
33040 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
33050 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33060 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
33070 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
33080 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
33090 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
330a0 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
330b0 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
330c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
330d0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
330e0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
330f0 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
33100 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
33110 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
33120 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
33130 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33140 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
33150 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
33160 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
33170 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
33180 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
33190 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
331a0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
331b0 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
331c0 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
331d0 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
331e0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
331f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
33200 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
33210 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
33220 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
33230 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
33240 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
33250 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
33260 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
33270 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d    Do <em>not</em
33280 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
33290 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
332a0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
332b0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
332c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
332d0 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
332e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
332f0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
33300 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
33310 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
33320 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
33330 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
33340 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
33350 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
33360 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
33370 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
33380 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
33390 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
333a0 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
333b0 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
333c0 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
333d0 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
333e0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
333f0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
33400 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
33410 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
33420 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
33430 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
33440 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
33450 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
33460 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33470 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
33480 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
33490 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
334a0 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
334b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
334c0 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
334d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
334e0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
334f0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
33500 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
33510 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
33520 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
33530 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
33540 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
33550 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
33560 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
33570 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
33580 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33590 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
335a0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
335b0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
335c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
335d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
335e0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
335f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
33600 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33610 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
33620 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
33630 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
33640 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
33650 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
33660 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
33670 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
33680 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
33690 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c   DESTRUCTOR: sql
336a0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
336b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
336c0 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
336d0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
336e0 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
336f0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
33700 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
33710 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
33720 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
33730 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65  encountered no e
33740 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74  rrors.** or if t
33750 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
33760 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75  never been evalu
33770 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ated, then sqlit
33780 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65  e3_finalize() re
33790 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f  turns.** SQLITE_
337a0 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73  OK.  ^If the mos
337b0 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
337c0 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74  ion of statement
337d0 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a   S failed, then.
337e0 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ** sqlite3_final
337f0 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74  ize(S) returns t
33800 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  he appropriate [
33810 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a  error code] or.*
33820 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  * [extended erro
33830 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
33840 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
33850 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20  lize(S) routine 
33860 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
33870 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
33880 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79  g.** the life cy
33890 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64  cle of [prepared
338a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a   statement] S:.*
338b0 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65  * before stateme
338c0 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61  nt S is ever eva
338d0 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a  luated, after.**
338e0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c   one or more cal
338f0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
33900 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65  eset()], or afte
33910 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f  r any call.** to
33920 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
33930 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  ] regardless of 
33940 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
33950 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
33960 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78  .** completed ex
33970 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ecution..**.** ^
33980 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  Invoking sqlite3
33990 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61  _finalize() on a
339a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
339b0 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
339c0 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  p..**.** The app
339d0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69  lication must fi
339e0 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72  nalize every [pr
339f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33a00 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76  ] in order to av
33a10 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20  oid.** resource 
33a20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20  leaks.  It is a 
33a30 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66  grievous error f
33a40 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
33a50 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65  on to try to use
33a60 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73  .** a prepared s
33a70 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
33a80 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
33a90 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f  ized.  Any use o
33aa0 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  f a prepared.** 
33ab0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
33ac0 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
33ad0 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74  lized can result
33ae0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
33af0 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  d.** undesirable
33b00 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61   behavior such a
33b10 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20  s segfaults and 
33b20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e  heap corruption.
33b30 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
33b40 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33  finalize(sqlite3
33b50 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
33b60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33b70 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64  Reset A Prepared
33b80 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
33b90 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
33ba0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
33bb0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
33bc0 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
33bd0 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
33be0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
33bf0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
33c00 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
33c10 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
33c20 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
33c30 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c  ted..** ^Any SQL
33c40 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
33c50 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
33c60 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
33c70 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
33c80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
33c90 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
33ca0 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
33cb0 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
33cc0 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
33cd0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
33ce0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
33cf0 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e  indings..**.** ^
33d00 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
33d10 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
33d20 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
33d30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33d40 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68   S.** back to th
33d50 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
33d60 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
33d70 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
33d80 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
33d90 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
33da0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
33db0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
33dc0 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
33dd0 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
33de0 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20  TE_DONE],.** or 
33df0 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
33e00 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
33e10 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
33e20 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20  d on S,.** then 
33e30 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
33e40 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
33e50 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  TE_OK]..**.** ^I
33e60 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
33e70 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
33e80 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
33e90 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
33ea0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
33eb0 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
33ec0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74  , then.** [sqlit
33ed0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
33ee0 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
33ef0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
33f00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
33f10 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
33f20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
33f30 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
33f40 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b  lues.** of any [
33f50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
33f60 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
33f70 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
33f80 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e  tement] S..*/.in
33f90 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
33fa0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
33fb0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
33fc0 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
33fd0 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
33fe0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  nctions.** KEYWO
33ff0 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
34000 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
34010 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
34020 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34030 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
34040 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
34050 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34060 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
34070 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  s}.** METHOD: sq
34080 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
34090 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  se functions (co
340a0 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
340b0 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
340c0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
340d0 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
340e0 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
340f0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
34100 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
34110 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
34120 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
34130 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
34140 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
34150 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62  ly differences b
34160 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20  etween.** these 
34170 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65  routines are the
34180 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65   text encoding e
34190 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74  xpected for.** t
341a0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
341b0 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66  ter (the name of
341c0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65   the function be
341d0 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20  ing created).** 
341e0 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65  and the presence
341f0 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61   or absence of a
34200 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
34210 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20  back for.** the 
34220 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
34230 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
34240 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
34250 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
34260 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34270 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
34280 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
34290 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
342a0 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ^If an applicati
342b0 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  on uses more tha
342c0 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a  n one database.*
342d0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65  * connection the
342e0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
342f0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
34300 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
34310 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74  d.** to each dat
34320 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34330 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
34340 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  ** ^The second p
34350 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
34360 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
34370 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
34380 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
34390 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65  efined.  ^The le
343a0 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
343b0 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
343c0 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54  55 bytes in a UT
343d0 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74  F-8.** represent
343e0 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65  ation, exclusive
343f0 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   of the zero-ter
34400 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20  minator.  ^Note 
34410 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  that the name.**
34420 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
34430 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c   in UTF-8 bytes,
34440 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20   not characters 
34450 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73  nor UTF-16 bytes
34460 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65  .  .** ^Any atte
34470 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
34480 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
34490 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
344a0 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
344b0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65  QLITE_MISUSE] be
344c0 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  ing returned..**
344d0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70  .** ^The third p
344e0 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a  arameter (nArg).
344f0 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
34500 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
34510 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
34520 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
34530 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74  ate takes. ^If t
34540 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
34550 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51   -1, then the SQ
34560 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
34570 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
34580 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
34590 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77  f arguments betw
345a0 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69  een 0 and the li
345b0 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73  mit.** set by [s
345c0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
345d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
345e0 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20  TION_ARG]).  If 
345f0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
34600 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74  ameter is less t
34610 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
34620 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20  r than 127 then 
34630 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a  the behavior is.
34640 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
34650 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
34660 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
34670 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
34680 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
34690 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
346a0 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
346b0 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
346c0 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
346d0 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69  ters.  The appli
346e0 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65  cation should se
346f0 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  t this parameter
34700 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   to.** [SQLITE_U
34710 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66  TF16LE] if the f
34720 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
34730 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a  tation invokes .
34740 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
34750 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e  e_text16le()] on
34760 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53   an input, or [S
34770 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69  QLITE_UTF16BE] i
34780 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
34790 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  ntation invokes 
347a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
347b0 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e  ext16be()] on an
347c0 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53   input, or.** [S
347d0 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20  QLITE_UTF16] if 
347e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
347f0 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64  ext16()] is used
34800 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
34810 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e  8].** otherwise.
34820 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20    ^The same SQL 
34830 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
34840 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69  registered multi
34850 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a  ple times using.
34860 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65  ** different pre
34870 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
34880 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66  dings, with diff
34890 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  erent implementa
348a0 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63  tions for.** eac
348b0 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e  h encoding..** ^
348c0 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
348d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
348e0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
348f0 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
34900 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
34910 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
34920 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
34930 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
34940 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
34950 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
34960 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  th parameter may
34970 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f   optionally be O
34980 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  Red with [SQLITE
34990 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a  _DETERMINISTIC].
349a0 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61  ** to signal tha
349b0 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77  t the function w
349c0 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72  ill always retur
349d0 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c  n the same resul
349e0 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73  t given.** the s
349f0 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69  ame inputs withi
34a00 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  n a single SQL s
34a10 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20  tatement.  Most 
34a20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  SQL functions ar
34a30 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74  e.** determinist
34a40 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69  ic.  The built-i
34a50 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c  n [random()] SQL
34a60 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20   function is an 
34a70 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20  example of a.** 
34a80 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73  function that is
34a90 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74   not determinist
34aa0 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ic.  The SQLite 
34ab0 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73  query planner is
34ac0 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66   able to.** perf
34ad0 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f  orm additional o
34ae0 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20  ptimizations on 
34af0 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75  deterministic fu
34b00 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a  nctions, so use.
34b10 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ** of the [SQLIT
34b20 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d  E_DETERMINISTIC]
34b30 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65   flag is recomme
34b40 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69  nded where possi
34b50 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ble..**.** ^(The
34b60 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
34b70 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
34b80 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
34b90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
34ba0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
34bb0 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
34bc0 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
34bd0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
34be0 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a  user_data()].)^.
34bf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
34c00 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69  , seventh and ei
34c10 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  ghth parameters,
34c20 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
34c30 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
34c40 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
34c50 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
34c60 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
34c70 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
34c80 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
34c90 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c  e. ^A scalar SQL
34ca0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
34cb0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
34cc0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e  tion of the xFun
34cd0 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  c.** callback on
34ce0 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly; NULL pointer
34cf0 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  s must be passed
34d00 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e   as the xStep an
34d10 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61  d xFinal.** para
34d20 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72  meters. ^An aggr
34d30 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
34d40 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
34d50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
34d60 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46   xStep.** and xF
34d70 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f  inal and NULL po
34d80 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61  inter must be pa
34d90 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
34da0 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78  ^To delete an ex
34db0 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
34dc0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
34dd0 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70  ate, pass NULL p
34de0 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20  ointers for all 
34df0 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  three function.*
34e00 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  * callbacks..**.
34e10 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74  ** ^(If the nint
34e20 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
34e30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
34e40 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e  nction_v2() is n
34e50 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e  ot NULL,.** then
34e60 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f   it is destructo
34e70 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
34e80 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
34e90 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74  er. .** The dest
34ea0 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65  ructor is invoke
34eb0 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74  d when the funct
34ec0 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20  ion is deleted, 
34ed0 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a  either by being.
34ee0 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72  ** overloaded or
34ef0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
34f00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
34f10 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  oses.)^.** ^The 
34f20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c  destructor is al
34f30 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68  so invoked if th
34f40 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  e call to.** sql
34f50 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
34f60 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e  tion_v2() fails.
34f70 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65  .** ^When the de
34f80 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
34f90 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70  k of the tenth p
34fa0 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f  arameter is invo
34fb0 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61  ked, it.** is pa
34fc0 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72  ssed a single ar
34fd0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
34fe0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70  a copy of the ap
34ff0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a  plication data .
35000 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  ** pointer which
35010 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70   was the fifth p
35020 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
35030 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35040 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ion_v2()..**.** 
35050 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64  ^It is permitted
35060 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
35070 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
35080 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
35090 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
350a0 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
350b0 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
350c0 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
350d0 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
350e0 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
350f0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
35100 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c  encodings.  ^SQL
35110 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
35120 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
35130 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f  on that most clo
35140 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
35150 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
35160 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
35170 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66  n is used.  ^A f
35180 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
35190 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
351a0 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
351b0 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
351c0 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
351d0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
351e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
351f0 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
35200 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74   nArg.  ^A funct
35210 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
35220 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
35230 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
35240 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
35250 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
35260 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
35270 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
35280 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
35290 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
352a0 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  * ^A function wh
352b0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
352c0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
352d0 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
352e0 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
352f0 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
35300 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
35310 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
35320 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
35330 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
35340 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
35350 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  * ^Built-in func
35360 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
35370 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
35380 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35390 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
353a0 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  .** ^An applicat
353b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
353c0 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
353d0 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
353e0 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
353f0 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
35400 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
35410 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
35420 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
35430 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
35440 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
35450 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
35460 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
35470 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
35480 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nning..*/.int sq
35490 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
354a0 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
354b0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
354c0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
354d0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
354e0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
354f0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
35500 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
35510 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
35520 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
35530 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
35540 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
35550 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
35560 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
35570 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
35580 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
35590 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
355a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
355b0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
355c0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
355d0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
355e0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
355f0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
35600 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
35610 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
35620 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
35630 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
35640 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
35650 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
35660 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
35670 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
35680 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
35690 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
356a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
356b0 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ction_v2(.  sqli
356c0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
356d0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
356e0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
356f0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
35700 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
35710 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
35720 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35730 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
35740 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
35750 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
35760 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
35770 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
35780 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
35790 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
357a0 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
357b0 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  oy)(void*).);../
357c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
357d0 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
357e0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
357f0 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
35800 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
35810 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
35820 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
35830 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
35840 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
35850 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
35860 20 20 20 20 20 20 20 20 20 20 20 31 20 20 20 20             1    
35870 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d  /* IMP: R-37514-
35880 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65  35566 */.#define
35890 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
358a0 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49         2    /* I
358b0 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33  MP: R-03371-3763
358c0 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  7 */.#define SQL
358d0 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
358e0 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20     3    /* IMP: 
358f0 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f  R-51971-34154 */
35900 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
35910 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
35920 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
35930 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
35940 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
35950 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
35960 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64     /* Deprecated
35970 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
35980 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
35990 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
359a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
359b0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
359c0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
359d0 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  tion Flags.**.**
359e0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
359f0 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67   may be ORed tog
35a00 65 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a  ether with the .
35a10 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
35a20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  | preferred text
35a30 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68   encoding] as th
35a40 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
35a50 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  t.** to [sqlite3
35a60 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
35a70 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
35a80 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
35a90 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
35aa0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35ab0 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65  on_v2()]..*/.#de
35ac0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45  fine SQLITE_DETE
35ad0 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38  RMINISTIC    0x8
35ae0 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
35af0 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
35b00 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
35b10 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
35b20 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
35b30 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
35b40 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
35b50 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
35b60 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
35b70 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
35b80 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
35b90 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
35ba0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
35bb0 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
35bc0 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
35bd0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
35be0 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
35bf0 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72  ions.  To encour
35c00 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72 73 20  age programmers 
35c10 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73  to avoid.** thes
35c20 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
35c30 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e  will not explain
35c40 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
35c50 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
35c60 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
35c70 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
35c80 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
35c90 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
35ca0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
35cb0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
35cc0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
35cd0 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
35ce0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
35cf0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
35d00 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
35d10 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
35d20 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
35d30 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
35d40 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
35d50 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
35d60 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
35d70 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
35d80 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
35d90 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
35da0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
35db0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
35dc0 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
35dd0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
35de0 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20  _int64,int),.   
35df0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35e00 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33     void*,sqlite3
35e10 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
35e20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35e30 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 56   Obtaining SQL V
35e40 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  alues.** METHOD:
35e50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a   sqlite3_value.*
35e60 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
35e70 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
35e80 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
35e90 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
35ea0 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
35eb0 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
35ec0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
35ed0 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
35ee0 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
35ef0 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
35f00 67 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a  ggregate.  .**.*
35f10 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
35f20 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
35f30 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
35f40 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
35f50 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
35f60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35f70 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
35f80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35f90 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
35fa0 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
35fb0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
35fc0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
35fd0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
35fe0 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61  .** The 3rd para
35ff0 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
36000 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
36010 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
36020 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
36030 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
36040 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
36050 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
36060 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
36070 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
36080 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
36090 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
360a0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
360b0 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
360c0 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
360d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
360e0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
360f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
36100 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
36110 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
36120 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
36130 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
36140 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
36150 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
36160 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
36170 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
36180 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
36190 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
361a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
361b0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
361c0 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
361d0 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20  ponding [column 
361e0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
361f0 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ].** except that
36200 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
36210 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
36220 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
36230 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
36240 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  * pointer instea
36250 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
36260 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
36270 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
36280 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
36290 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
362a0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
362b0 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
362c0 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
362d0 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
362e0 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
362f0 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
36300 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
36310 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
36320 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
36330 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
36340 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
36350 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
36360 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
36370 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
36380 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
36390 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
363a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
363b0 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
363c0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
363d0 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
363e0 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
363f0 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
36400 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
36410 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
36420 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
36430 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
36440 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
36450 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
36460 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
36470 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
36480 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
36490 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
364a0 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
364b0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
364c0 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
364d0 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
364e0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
364f0 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
36500 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
36510 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
36520 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
36530 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
36540 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
36550 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
36560 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
36570 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
36580 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
36590 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
365a0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74   the pointer ret
365b0 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
365c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
365d0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
365e0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
365f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
36600 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
36610 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
36620 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
36630 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
36640 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
36650 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
36660 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
36670 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
36680 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
36690 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
366a0 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  16()]..**.** The
366b0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
366c0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
366d0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
366e0 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
366f0 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
36700 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
36710 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
36720 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  ters..*/.const v
36730 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
36740 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
36750 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
36760 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
36770 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
36780 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
36790 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
367a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
367b0 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
367c0 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
367d0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
367e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
367f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
36800 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
36810 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
36820 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
36830 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
36840 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
36850 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
36860 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
36870 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
36880 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
36890 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
368a0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
368b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
368c0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
368d0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
368e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
368f0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
36900 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
36910 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
36920 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
36930 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
36940 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
36950 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
36960 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36970 46 69 6e 64 69 6e 67 20 54 68 65 20 53 75 62 74  Finding The Subt
36980 79 70 65 20 4f 66 20 53 51 4c 20 56 61 6c 75 65  ype Of SQL Value
36990 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
369a0 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a  ite3_value.**.**
369b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
369c0 75 65 5f 73 75 62 74 79 70 65 28 56 29 20 66 75  ue_subtype(V) fu
369d0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
369e0 68 65 20 73 75 62 74 79 70 65 20 66 6f 72 0a 2a  he subtype for.*
369f0 2a 20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f  * an [applicatio
36a00 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
36a10 6e 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74  nction] argument
36a20 20 56 2e 20 20 54 68 65 20 73 75 62 74 79 70 65   V.  The subtype
36a30 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
36a40 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 70  can be used to p
36a50 61 73 73 20 61 20 6c 69 6d 69 74 65 64 20 61 6d  ass a limited am
36a60 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74 20  ount of context 
36a70 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20  from.** one SQL 
36a80 66 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74  function to anot
36a90 68 65 72 2e 20 20 55 73 65 20 74 68 65 20 5b 73  her.  Use the [s
36aa0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75  qlite3_result_su
36ab0 62 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74  btype()].** rout
36ac0 69 6e 65 20 74 6f 20 73 65 74 20 74 68 65 20 73  ine to set the s
36ad0 75 62 74 79 70 65 20 66 6f 72 20 74 68 65 20 72  ubtype for the r
36ae0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61  eturn value of a
36af0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a  n SQL function..
36b00 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  **.** SQLite mak
36b10 65 73 20 6e 6f 20 75 73 65 20 6f 66 20 73 75 62  es no use of sub
36b20 74 79 70 65 20 69 74 73 65 6c 66 2e 20 20 49 74  type itself.  It
36b30 20 6d 65 72 65 6c 79 20 70 61 73 73 65 73 20 74   merely passes t
36b40 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 66 72  he subtype.** fr
36b50 6f 6d 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  om the result of
36b60 20 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74 69 6f   one [applicatio
36b70 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
36b80 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65  nction] into the
36b90 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f  .** input of ano
36ba0 74 68 65 72 2e 0a 2a 2f 0a 75 6e 73 69 67 6e 65  ther..*/.unsigne
36bb0 64 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  d int sqlite3_va
36bc0 6c 75 65 5f 73 75 62 74 79 70 65 28 73 71 6c 69  lue_subtype(sqli
36bd0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
36be0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
36bf0 70 79 20 41 6e 64 20 46 72 65 65 20 53 51 4c 20  py And Free SQL 
36c00 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  Values.** METHOD
36c10 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a  : sqlite3_value.
36c20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36c30 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20  e3_value_dup(V) 
36c40 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
36c50 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
36c60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
36c70 20 6f 62 6a 65 63 74 20 44 20 61 6e 64 20 72 65   object D and re
36c80 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
36c90 74 6f 20 74 68 61 74 20 63 6f 70 79 2e 20 20 5e  to that copy.  ^
36ca0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
36cb0 75 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ue] returned.** 
36cc0 69 73 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20  is a [protected 
36cd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
36ce0 62 6a 65 63 74 20 65 76 65 6e 20 69 66 20 74 68  bject even if th
36cf0 65 20 69 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a  e input is not..
36d00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36d10 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74  value_dup(V) int
36d20 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e  erface returns N
36d30 55 4c 4c 20 69 66 20 56 20 69 73 20 4e 55 4c 4c  ULL if V is NULL
36d40 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f   or if a.** memo
36d50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
36d60 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ils..**.** ^The 
36d70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72  sqlite3_value_fr
36d80 65 65 28 56 29 20 69 6e 74 65 72 66 61 63 65 20  ee(V) interface 
36d90 66 72 65 65 73 20 61 6e 20 5b 73 71 6c 69 74 65  frees an [sqlite
36da0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
36db0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
36dc0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
36dd0 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29  ite3_value_dup()
36de0 5d 2e 20 20 5e 49 66 20 56 20 69 73 20 61 20 4e  ].  ^If V is a N
36df0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
36e00 68 65 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  hen sqlite3_valu
36e10 65 5f 66 72 65 65 28 56 29 20 69 73 20 61 20 68  e_free(V) is a h
36e20 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
36e30 2f 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  /.sqlite3_value 
36e40 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  *sqlite3_value_d
36e50 75 70 28 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  up(const sqlite3
36e60 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73  _value*);.void s
36e70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65  qlite3_value_fre
36e80 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
36e90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36ea0 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
36eb0 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
36ec0 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ntext.** METHOD:
36ed0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
36ee0 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74  .**.** Implement
36ef0 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67  ations of aggreg
36f00 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
36f10 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f  s use this.** ro
36f20 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
36f30 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f  e memory for sto
36f40 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
36f50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
36f60 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
36f70 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
36f80 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
36f90 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a  ne is called .**
36fa0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
36fb0 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  r aggregate func
36fc0 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  tion, SQLite.** 
36fd0 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d  allocates N of m
36fe0 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
36ff0 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  t that memory, a
37000 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
37010 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e  nter.** to the n
37020 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73  ew memory. ^On s
37030 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
37040 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
37050 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
37060 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
37070 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
37080 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
37090 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61  tance,.** the sa
370a0 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
370b0 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f  urned.  Sqlite3_
370c0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
370d0 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a  t() is normally.
370e0 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66  ** called once f
370f0 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  or each invocati
37100 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20  on of the xStep 
37110 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65  callback and the
37120 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69  n one.** last ti
37130 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e  me when the xFin
37140 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  al callback is i
37150 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20  nvoked.  ^(When 
37160 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a  no rows match.**
37170 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75   an aggregate qu
37180 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29  ery, the xStep()
37190 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
371a0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
371b0 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ion.** implement
371c0 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63  ation is never c
371d0 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c  alled and xFinal
371e0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61  () is called exa
371f0 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e  ctly once..** In
37200 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71   those cases, sq
37210 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
37220 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20  context() might 
37230 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  be called for th
37240 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20  e.** first time 
37250 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e  from within xFin
37260 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  al().)^.**.** ^T
37270 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
37280 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
37290 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
372a0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
372b0 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20   .** when first 
372c0 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c  called if N is l
372d0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
372e0 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20  l to zero or if 
372f0 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  a memory.** allo
37300 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72  cate error occur
37310 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
37320 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61  mount of space a
37330 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
37340 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
37350 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a  ntext(C,N) is.**
37360 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
37370 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f  he N parameter o
37380 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66  n first successf
37390 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69  ul call.  Changi
373a0 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  ng the.** value 
373b0 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65  of N in subseque
373c0 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
373d0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
373e0 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a  text() within.**
373f0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
37400 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
37410 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72  tance will not r
37420 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  esize the memory
37430 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29  .** allocation.)
37440 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46  ^  Within the xF
37450 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69  inal callback, i
37460 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74  t is customary t
37470 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20  o set.** N=0 in 
37480 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
37490 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
374a0 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20  xt(C,N) so that 
374b0 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73  no .** pointless
374c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
374d0 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a  ons occur..**.**
374e0 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74   ^SQLite automat
374f0 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65  ically frees the
37500 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
37510 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
37520 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
37530 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67  xt() when the ag
37540 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f  gregate query co
37550 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
37560 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
37570 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70  er must be a cop
37580 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  y of the.** [sql
37590 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
375a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
375b0 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
375c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
375d0 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70  .** to the xStep
375e0 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
375f0 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
37600 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
37610 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e  aggregate.** fun
37620 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
37630 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
37640 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
37650 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
37660 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
37670 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
37680 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
37690 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
376a0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
376b0 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
376c0 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73  ext*, int nBytes
376d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
376e0 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f  EF: User Data Fo
376f0 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d  r Functions.** M
37700 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63  ETHOD: sqlite3_c
37710 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  ontext.**.** ^Th
37720 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
37730 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
37740 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
37750 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
37760 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
37770 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
37780 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
37790 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
377a0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
377b0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
377c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
377d0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
377e0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
377f0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
37800 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
37810 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
37820 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
37830 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
37840 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
37850 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
37860 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
37870 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
37880 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
37890 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
378a0 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
378b0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
378c0 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
378d0 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
378e0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72  e Connection For
378f0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45   Functions.** ME
37900 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f  THOD: sqlite3_co
37910 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ntext.**.** ^The
37920 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
37930 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
37940 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
37950 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
37960 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
37970 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37980 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
37990 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
379a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
379b0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
379c0 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
379d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
379e0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
379f0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
37a00 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
37a10 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
37a20 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a  ed function..*/.
37a30 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
37a40 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
37a50 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
37a60 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
37a70 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
37a80 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
37a90 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
37aa0 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  3_context.**.** 
37ab0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
37ac0 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 28  may be used by (
37ad0 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53  non-aggregate) S
37ae0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a  QL functions to.
37af0 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74  ** associate met
37b00 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  adata with argum
37b10 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
37b20 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
37b30 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
37b40 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
37b50 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
37b60 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
37b70 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
37b80 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
37b90 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
37ba0 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
37bb0 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70  etadata may be p
37bc0 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78  reserved.  An ex
37bd0 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72  ample.** of wher
37be0 65 20 74 68 69 73 20 6d 69 67 68 74 20 62 65 20  e this might be 
37bf0 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72  useful is in a r
37c00 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
37c10 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75  n matching.** fu
37c20 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
37c30 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
37c40 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
37c50 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74  ession can be st
37c60 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64  ored as.** metad
37c70 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
37c80 69 74 68 20 74 68 65 20 70 61 74 74 65 72 6e 20  ith the pattern 
37c90 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65  string.  .** The
37ca0 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  n as long as the
37cb0 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20   pattern string 
37cc0 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65  remains the same
37cd0 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65  ,.** the compile
37ce0 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
37cf0 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
37d00 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
37d10 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
37d20 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
37d30 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
37d40 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
37d50 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
37d60 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
37d70 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
37d80 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
37d90 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
37da0 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
37db0 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
37dc0 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
37dd0 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
37de0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
37df0 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65  unction. ^If the
37e00 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74  re is no metadat
37e10 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
37e20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f  with the functio
37e30 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73  n argument, this
37e40 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
37e50 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
37e60 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55  .** returns a NU
37e70 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
37e80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
37e90 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
37ea0 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  ,X) interface sa
37eb0 76 65 73 20 50 20 61 73 20 6d 65 74 61 64 61 74  ves P as metadat
37ec0 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a  a for the N-th.*
37ed0 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  * argument of th
37ee0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
37ef0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
37f00 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20   ^Subsequent.** 
37f10 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
37f20 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _get_auxdata(C,N
37f30 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20  ) return P from 
37f40 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
37f50 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
37f60 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
37f70 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61  call if the meta
37f80 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61  data is still va
37f90 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69  lid or.** NULL i
37fa0 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 68  f the metadata h
37fb0 61 73 20 62 65 65 6e 20 64 69 73 63 61 72 64 65  as been discarde
37fc0 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63  d..** ^After eac
37fd0 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
37fe0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
37ff0 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20 69  N,P,X) where X i
38000 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53  s not NULL,.** S
38010 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
38020 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
38030 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68   function X with
38040 20 70 61 72 61 6d 65 74 65 72 20 50 20 65 78 61   parameter P exa
38050 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68  ctly.** once, wh
38060 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  en the metadata 
38070 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a  is discarded..**
38080 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
38090 74 6f 20 64 69 73 63 61 72 64 20 74 68 65 20 6d  to discard the m
380a0 65 74 61 64 61 74 61 20 61 74 20 61 6e 79 20 74  etadata at any t
380b0 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20  ime, including: 
380c0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5e 28 77  <ul>.** <li> ^(w
380d0 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
380e0 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
380f0 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
38100 29 5e 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5e  )^, or.** <li> ^
38110 28 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72  (when [sqlite3_r
38120 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
38130 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
38140 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  is called for th
38150 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74  e.**      SQL st
38160 61 74 65 6d 65 6e 74 29 5e 2c 20 6f 72 0a 2a 2a  atement)^, or.**
38170 20 3c 6c 69 3e 20 5e 28 77 68 65 6e 20 73 71 6c   <li> ^(when sql
38180 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
38190 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67  () is invoked ag
381a0 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  ain on the same.
381b0 2a 2a 20 20 20 20 20 20 20 70 61 72 61 6d 65 74  **       paramet
381c0 65 72 29 5e 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  er)^, or.** <li>
381d0 20 5e 28 64 75 72 69 6e 67 20 74 68 65 20 6f 72   ^(during the or
381e0 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73  iginal sqlite3_s
381f0 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c  et_auxdata() cal
38200 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20  l when a memory 
38210 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74  .**      allocat
38220 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
38230 2e 29 5e 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .)^ </ul>.**.** 
38240 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75  Note the last bu
38250 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c  llet in particul
38260 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  ar.  The destruc
38270 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c  tor X in .** sql
38280 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
38290 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20  (C,N,P,X) might 
382a0 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69  be called immedi
382b0 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68  ately, before th
382c0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  e.** sqlite3_set
382d0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
382e0 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e  face even return
382f0 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65  s.  Hence sqlite
38300 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a  3_set_auxdata().
38310 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c  ** should be cal
38320 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64  led near the end
38330 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
38340 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
38350 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  and the.** funct
38360 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
38370 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61  on should not ma
38380 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20  ke any use of P 
38390 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33  after.** sqlite3
383a0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68  _set_auxdata() h
383b0 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a  as been called..
383c0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
383d0 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
383e0 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
383f0 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
38400 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  s for.** functio
38410 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
38420 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69  t are compile-ti
38430 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e  me constants, in
38440 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a  cluding literal.
38450 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
38460 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65  arameters] and e
38470 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f  xpressions compo
38480 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  sed from the sam
38490 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  e.)^.**.** These
384a0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
384b0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
384c0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
384d0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
384e0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
384f0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
38500 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
38510 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
38520 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
38530 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
38540 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
38550 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
38560 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
38570 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
38580 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
38590 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
385a0 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
385b0 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
385c0 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
385d0 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
385e0 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
385f0 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
38600 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
38610 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
38620 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
38630 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
38640 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
38650 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
38660 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
38670 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
38680 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
38690 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
386a0 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
386b0 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
386c0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
386d0 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
386e0 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
386f0 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
38700 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
38710 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
38720 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
38730 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
38740 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
38750 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
38760 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
38770 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
38780 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
38790 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
387a0 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
387b0 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
387c0 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
387d0 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
387e0 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  ilers..*/.typede
387f0 66 20 76