/ Hex Artifact Content
Login

Artifact 89b948cfa352cca946a5b20d9378df30d612f282:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65  LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 5b 76 65 72 73 69 6f  ** Since [versio
0f00: 6e 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65  n 3.6.18] ([date
0f10: 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a  of:3.6.18]), .**
0f20: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
0f30: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
0f40: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
0f50: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
0f60: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
0f70: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
0f80: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0f90: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
0fa0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
0fb0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
0fc0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
0fd0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
0fe0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
0ff0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
1000: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
1010: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
1020: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
1030: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
1040: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
1050: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
1060: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
1070: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
1080: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e  -in (UTC) and an
1090: 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66   SHA1.** hash of
10a0: 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72   the entire sour
10b0: 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53  ce tree..**.** S
10c0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
10d0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c  3_libversion()],
10e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  .** [sqlite3_lib
10f0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
1100: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72  ], [sqlite3_sour
1110: 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ceid()],.** [sql
1120: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
1130: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
1140: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  e_id()]..*/.#def
1150: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ine SQLITE_VERSI
1160: 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52  ON        "--VER
1170: 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c  S--".#define SQL
1180: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1190: 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d  ER --VERSION-NUM
11a0: 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65 20 53 51  BER--.#define SQ
11b0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20  LITE_SOURCE_ID  
11c0: 20 20 20 20 22 2d 2d 53 4f 55 52 43 45 2d 49 44      "--SOURCE-ID
11d0: 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  --"../*.** CAPI3
11e0: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
11f0: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75  brary Version Nu
1200: 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  mbers.** KEYWORD
1210: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  S: sqlite3_versi
1220: 6f 6e 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  on sqlite3_sourc
1230: 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  eid.**.** These 
1240: 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69  interfaces provi
1250: 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  de the same info
1260: 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b  rmation as the [
1270: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c  SQLITE_VERSION],
1280: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1290: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64  ION_NUMBER], and
12a0: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
12b0: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
12c0: 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74  or macros.** but
12d0: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20   are associated 
12e0: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79  with the library
12f0: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1300: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28  header file.  ^(
1310: 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67  Cautious.** prog
1320: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e  rammers might in
1330: 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73  clude assert() s
1340: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
1350: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
1360: 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74  o.** verify that
1370: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
1380: 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66   by these interf
1390: 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d  aces match the m
13a0: 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20  acros in.** the 
13b0: 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73  header, and thus
13c0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
13d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a   application is.
13e0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
13f0: 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72   matching librar
1400: 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c  y and header fil
1410: 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  es..**.** <block
1420: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61  quote><pre>.** a
1430: 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c  ssert( sqlite3_l
1440: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1450: 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49  ()==SQLITE_VERSI
1460: 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20  ON_NUMBER );.** 
1470: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73  assert( strcmp(s
1480: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1490: 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  ),SQLITE_SOURCE_
14a0: 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73  ID)==0 );.** ass
14b0: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69  ert( strcmp(sqli
14c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
14d0: 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29  ,SQLITE_VERSION)
14e0: 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ==0 );.** </pre>
14f0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1500: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1510: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1520: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e  ing constant con
1530: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f  tains the text o
1540: 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  f [SQLITE_VERSIO
1550: 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54  N].** macro.  ^T
1560: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
1570: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e  rsion() function
1580: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1590: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20  er to the.** to 
15a0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  the sqlite3_vers
15b0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
15c0: 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  stant.  The sqli
15d0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
15e0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
15f0: 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65  provided for use
1600: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44   in DLLs since D
1610: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79  LL users usually
1620: 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20   do not have.** 
1630: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f  direct access to
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1650: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c  s within the DLL
1660: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
1670: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1680: 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20  mber() function 
1690: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
16a0: 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b  er equal to.** [
16b0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
16c0: 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71  UMBER].  ^The sq
16d0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
16e0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
16f0: 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
1700: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73  to a string cons
1710: 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65  tant whose value
1720: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
1730: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
1740: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1750: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e  processor macro.
1760: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1770: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e   [sqlite_version
1780: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f  ()] and [sqlite_
1790: 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f  source_id()]..*/
17a0: 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
17b0: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65  onst char sqlite
17c0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e  3_version[];.con
17d0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
17e0: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64  _libversion(void
17f0: 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
1800: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1810: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
1820: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1830: 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  mber(void);../*.
1840: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1850: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f  -Time Library Co
1860: 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  mpilation Option
1870: 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a  s Diagnostics.**
1880: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1890: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
18a0: 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  sed() function r
18b0: 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a  eturns 0 or 1 .*
18c0: 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65  * indicating whe
18d0: 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69  ther the specifi
18e0: 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65  ed option was de
18f0: 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d  fined at .** com
1900: 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65  pile time.  ^The
1910: 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20   SQLITE_ prefix 
1920: 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66  may be omitted f
1930: 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69  rom the .** opti
1940: 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74  on name passed t
1950: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  o sqlite3_compil
1960: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20  eoption_used(). 
1970: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f  on_get() functio
19a0: 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69  n allows iterati
19b0: 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c  ng.** over the l
19c0: 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74  ist of options t
19d0: 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64  hat were defined
19e0: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
19f0: 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67   by.** returning
1a00: 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c   the N-th compil
1a10: 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74  e time option st
1a20: 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20  ring.  ^If N is 
1a30: 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a  out of range,.**
1a40: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1a50: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74  option_get() ret
1a60: 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1a70: 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ter.  ^The SQLIT
1a80: 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73  E_ .** prefix is
1a90: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e   omitted from an
1aa0: 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  y strings return
1ab0: 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
1ac0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1ad0: 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75  get()..**.** ^Su
1ae0: 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69  pport for the di
1af0: 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f  agnostic functio
1b00: 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ns sqlite3_compi
1b10: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a  leoption_used().
1b20: 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
1b30: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b40: 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  () may be omitte
1b50: 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20  d by specifying 
1b60: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
1b70: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
1b80: 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e  ON_DIAGS] option
1b90: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
1ba0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1bb0: 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  : SQL functions 
1bc0: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f  [sqlite_compileo
1bd0: 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e  ption_used()] an
1be0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  d.** [sqlite_com
1bf0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1c00: 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69  ] and the [compi
1c10: 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d  le_options pragm
1c20: 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  a]..*/.#ifndef S
1c30: 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49  QLITE_OMIT_COMPI
1c40: 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 69  LEOPTION_DIAGS.i
1c50: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nt sqlite3_compi
1c60: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f  leoption_used(co
1c70: 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61  nst char *zOptNa
1c80: 6d 65 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  me);.const char 
1c90: 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65  *sqlite3_compile
1ca0: 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e  option_get(int N
1cb0: 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
1cc0: 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
1cd0: 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69  To See If The Li
1ce0: 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73  brary Is Threads
1cf0: 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  afe.**.** ^The s
1d00: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1d10: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  e() function ret
1d20: 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64  urns zero if and
1d30: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69   only if.** SQLi
1d40: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  te was compiled 
1d50: 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f  with mutexing co
1d60: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1d70: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1d80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1d90: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1da0: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1db0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1dc0: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1dd0: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1de0: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1df0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1e00: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1e10: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1e20: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1e30: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1e40: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1e50: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1e60: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1e70: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1e80: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1e90: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1ea0: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1eb0: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1ec0: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1ed0: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1ee0: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1ef0: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1f00: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1f10: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1f20: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1f30: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1f40: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1f50: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1f60: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1f70: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1f80: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1f90: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1fa0: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1fb0: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1fc0: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1fd0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1fe0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1ff0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2010: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
2020: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
2030: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
2040: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
2050: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
2060: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
2070: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
2080: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
2090: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
20a0: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
20b0: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
20c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
20d0: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
20e0: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
20f0: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
2100: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
2110: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
2120: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
2130: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
2140: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
2150: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
2160: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
2170: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2180: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2190: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
21a0: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
21b0: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
21c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
21d0: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
21e0: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
21f0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2200: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2210: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
2220: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
2230: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
2240: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
2250: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
2260: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
2270: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2280: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2290: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
22a0: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
22b0: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
22c0: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
22d0: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
22e0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
22f0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2300: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2310: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
2320: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
2330: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
2340: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
2350: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
2360: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
2370: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2380: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2390: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
23a0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
23b0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23c0: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
23d0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23e0: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
23f0: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2400: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2410: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2420: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
2430: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
2440: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
2450: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
2460: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
2470: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2480: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2490: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
24a0: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
24b0: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
24c0: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
24d0: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
24e0: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
24f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2500: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2510: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
2520: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2530: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
2540: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
2550: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
2560: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
2570: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2580: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2590: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
25a0: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
25b0: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
25c0: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
25d0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
25e0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
25f0: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2600: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2610: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
2620: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
2630: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
2640: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
2650: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
2660: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2670: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2680: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2690: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
26a0: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
26b0: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
26c0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
26d0: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
26e0: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
26f0: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2700: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2710: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
2720: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
2730: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
2740: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
2750: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
2760: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2770: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2780: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2790: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
27a0: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
27b0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
27c0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
27d0: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
27e0: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
27f0: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2800: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2810: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2820: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
2830: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
2840: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
2850: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
2860: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
2870: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2880: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2890: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
28a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
28b0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
28c0: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
28d0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
28e0: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
28f0: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2900: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2910: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
2920: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2930: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
2940: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
2950: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 23 20  sqlite_int64;.# 
2960: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 55 49 4e  ifdef SQLITE_UIN
2970: 54 36 34 5f 54 59 50 45 0a 20 20 20 20 74 79 70  T64_TYPE.    typ
2980: 65 64 65 66 20 53 51 4c 49 54 45 5f 55 49 4e 54  edef SQLITE_UINT
2990: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75  64_TYPE sqlite_u
29a0: 69 6e 74 36 34 3b 0a 23 20 65 6c 73 65 20 20 0a  int64;.# else  .
29b0: 20 20 20 20 74 79 70 65 64 65 66 20 75 6e 73 69      typedef unsi
29c0: 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36  gned SQLITE_INT6
29d0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69  4_TYPE sqlite_ui
29e0: 6e 74 36 34 3b 0a 23 20 65 6e 64 69 66 0a 23 65  nt64;.# endif.#e
29f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2a00: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2a10: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2a20: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2a30: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2a40: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2a50: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2a60: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2a70: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2a80: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2a90: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2aa0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
2ab0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
2ac0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
2ad0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
2ae0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
2af0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2b00: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2b10: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2b20: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2b30: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2b40: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2b50: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2b60: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2b70: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2b80: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2b90: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
2ba0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
2bb0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
2bc0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
2bd0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2be0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
2bf0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2c00: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
2c10: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
2c20: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
2c30: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2c40: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65  ose_v2() routine
2c50: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72  s are destructor
2c60: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71  s.** for the [sq
2c70: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2c80: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2c90: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2ca0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2cb0: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  () return [SQLIT
2cc0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20  E_OK] if.** the 
2cd0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2ce0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79   is successfully
2cf0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
2d00: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
2d10: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64   resources are d
2d20: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a  eallocated..**.*
2d30: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2d40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2d50: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2d60: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2d70: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2d80: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65  nts or unfinishe
2d90: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
2da0: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71   objects then sq
2db0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
2dc0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
2dd0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2de0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74  ion open and ret
2df0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
2e00: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
2e10: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
2e20: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69  called with unfi
2e30: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2e40: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
2e50: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  nd/or unfinished
2e60: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73   sqlite3_backups
2e70: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
2e80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
2e90: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75  ecomes.** an unu
2ea0: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77  sable "zombie" w
2eb0: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61  hich will automa
2ec0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c  tically be deall
2ed0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a  ocated when the.
2ee0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  ** last prepared
2ef0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2f00: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c  nalized or the l
2f10: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ast sqlite3_back
2f20: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65  up is.** finishe
2f30: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
2f40: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72  close_v2() inter
2f50: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
2f60: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a   for use with.**
2f70: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20   host languages 
2f80: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65  that are garbage
2f90: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20   collected, and 
2fa0: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20  where the order 
2fb0: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74  in which.** dest
2fc0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c  ructors are call
2fd0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  ed is arbitrary.
2fe0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2ff0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
3000: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
3010: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
3020: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3030: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
3040: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
3050: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
3060: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20  ndles], and .** 
3070: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
3080: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d  finish | finish]
3090: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61   all [sqlite3_ba
30a0: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73  ckup] objects as
30b0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
30c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
30d0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
30e0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
30f0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
3100: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
3110: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
3120: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
3130: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
3140: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
3150: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
3160: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3170: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3180: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
3190: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
31a0: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
31b0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
31c0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c  K] and the deall
31d0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
31e0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
31f0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
3200: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
3210: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
3220: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
3230: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
3240: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
3250: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
3260: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
3270: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
3280: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
3290: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
32a0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
32b0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
32c0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
32d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
32e0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
32f0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
3300: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
3310: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
3320: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
3330: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
3340: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
3350: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
3360: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3370: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
3380: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
3390: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
33a0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
33b0: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
33c0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
33d0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
33e0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
33f0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
3400: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
3410: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
3420: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
3430: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
3440: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69  ose(sqlite3*);.i
3450: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3460: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
3470: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
3480: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
3490: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
34a0: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
34b0: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
34c0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
34d0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
34e0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
34f0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
3500: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
3510: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
3520: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3530: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
3540: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3550: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
3560: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
3570: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
3580: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
3590: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
35a0: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
35b0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
35c0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
35d0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
35e0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
35f0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
3600: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
3610: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3620: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3630: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3640: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3650: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3660: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3670: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3680: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3690: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
36a0: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
36b0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
36c0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
36d0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
36e0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
36f0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
3700: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
3710: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3720: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3730: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3740: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3750: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3760: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3770: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3780: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3790: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
37a0: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
37b0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
37c0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
37d0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
37e0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
37f0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
3800: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3810: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3820: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3830: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3840: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3850: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3860: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3870: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3880: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3890: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
38a0: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
38b0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
38c0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
38d0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
38e0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
38f0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
3900: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
3910: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3920: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3940: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3950: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3960: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3970: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3980: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3990: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
39a0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
39b0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
39c0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
39d0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
39e0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
39f0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
3a00: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3a10: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3a20: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3a30: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3a40: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3a50: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3a60: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3a70: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3a80: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3a90: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3aa0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3ab0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
3ac0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
3ad0: 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  eter of.** sqlit
3ae0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20  e3_exec() after 
3af0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
3b00: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c  e string is no l
3b10: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3b20: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3b30: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3b40: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3b50: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f  NULL and no erro
3b60: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65  rs.** occur, the
3b70: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3b80: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65   sets the pointe
3b90: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72  r in its 5th par
3ba0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c  ameter to.** NUL
3bb0: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  L before returni
3bc0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ng..**.** ^If an
3bd0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3be0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
3bf0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73   non-zero, the s
3c00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3c10: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
3c20: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69   SQLITE_ABORT wi
3c30: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74  thout invoking t
3c40: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69  he callback agai
3c50: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74  n and.** without
3c60: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62   running any sub
3c70: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
3c80: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
3c90: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20  he 2nd argument 
3ca0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3cb0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66  xec() callback f
3cc0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a  unction is the.*
3cd0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  * number of colu
3ce0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
3cf0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67  t.  ^The 3rd arg
3d00: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3d10: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63  ite3_exec().** c
3d20: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
3d30: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3d40: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69  to strings obtai
3d50: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a  ned as if from.*
3d60: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
3d70: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66  n_text()], one f
3d80: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20  or each column. 
3d90: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20   ^If an element 
3da0: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72  of a.** result r
3db0: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ow is NULL then 
3dc0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
3dd0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  g string pointer
3de0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69   for the.** sqli
3df0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3e00: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ack is a NULL po
3e10: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68  inter.  ^The 4th
3e20: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e30: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3e40: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3e50: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e60: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
3e70: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74  here each.** ent
3e80: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68  ry represents th
3e90: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73  e name of corres
3ea0: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63  ponding result c
3eb0: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65  olumn as obtaine
3ec0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3ed0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
3ee0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
3ef0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
3f00: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3f10: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3f20: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  er, a pointer.**
3f30: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
3f40: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65  ing, or a pointe
3f50: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  r that contains 
3f60: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20  only whitespace 
3f70: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63  and/or .** SQL c
3f80: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
3f90: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3fa0: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
3fb0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  d the database.*
3fc0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
3fd0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74  ..**.** Restrict
3fe0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ions:.**.** <ul>
3ff0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
4000: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e  lication must en
4010: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73  sure that the 1s
4020: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
4030: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
4040: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64        is a valid
4050: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62   and open [datab
4060: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
4070: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
4080: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
4090: 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74  t close the [dat
40a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
40b0: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
40c0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
40d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
40e0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
40f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4100: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
4110: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4120: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
4130: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
4140: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
4150: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
4160: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
4170: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
4180: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
4190: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
41a0: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
41b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
41c0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
41f0: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
4200: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
4210: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4230: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
4240: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
4250: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
4260: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
4270: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
4280: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
4290: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
42c0: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
42d0: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
42e0: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4300: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
4310: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
4320: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
4330: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
4340: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4350: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
4360: 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a  de definitions}.
4370: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
4380: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
4390: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
43a0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
43b0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
43c0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
43d0: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73   indicate succes
43e0: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
43f0: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f  .** New error co
4400: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  des may be added
4410: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
4420: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
4430: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
4440: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4450: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  code definitions
4460: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ].*/.#define SQL
4470: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
4480: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4490: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
44a0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
44b0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
44c0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
44d0: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
44e0: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
44f0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4510: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4520: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
4530: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
4540: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4550: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
4560: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
4570: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
4580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4590: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
45a0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
45b0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
45c0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
45d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
45e0: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
45f0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4600: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4610: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4620: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4630: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4640: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4650: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4660: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
4670: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
4680: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4690: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
46a0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
46b0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
46c0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
46d0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
46e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
46f0: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4700: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4710: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4720: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4730: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4740: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4750: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4760: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
4770: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
4780: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4790: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
47a0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
47b0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
47c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
47d0: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
47e0: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
47f0: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4800: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4820: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4830: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4840: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4850: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4870: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
4880: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4890: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
48a0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
48b0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
48c0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
48d0: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
48e0: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
48f0: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4900: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4910: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4920: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4930: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4940: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4950: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4960: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4970: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
4980: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4990: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
49a0: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
49b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
49c0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
49d0: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
49e0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
49f0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4a00: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4a10: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4a20: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4a30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4a40: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4a50: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4a60: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
4a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
4a80: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4a90: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4aa0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4ab0: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
4ac0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4ad0: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4ae0: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4af0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4b00: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4b10: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4b20: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4b30: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4b40: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4b50: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4b60: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4b70: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4b80: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4b90: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4ba0: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4bb0: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4bc0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4bd0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4be0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20  e SQLITE_NOTICE 
4bf0: 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74       27   /* Not
4c00: 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20  ifications from 
4c10: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4c20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c30: 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20  WARNING     28  
4c40: 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f   /* Warnings fro
4c50: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
4c60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4c70: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
4c80: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
4c90: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
4ca0: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
4cb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
4cc0: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
4cd0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4ce0: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
4cf0: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
4d00: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4d10: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
4d20: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
4d30: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
4d40: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
4d50: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66   result code def
4d60: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  initions}.**.** 
4d70: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4d80: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4d90: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4da0: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4db0: 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72  30 integer.** [r
4dc0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48  esult codes].  H
4dd0: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e  owever, experien
4de0: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61  ce has shown tha
4df0: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65  t many of.** the
4e00: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  se result codes 
4e10: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67  are too coarse-g
4e20: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f  rained.  They do
4e30: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a   not provide as.
4e40: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74  ** much informat
4e50: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65  ion about proble
4e60: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72  ms as programmer
4e70: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49  s might like.  I
4e80: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a  n an effort to.*
4e90: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20  * address this, 
4ea0: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
4eb0: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f  f SQLite (versio
4ec0: 6e 20 33 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a  n 3.3.8 [dateof:
4ed0: 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61  3.3.8].** and la
4ee0: 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20  ter) include.** 
4ef0: 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69  support for addi
4f00: 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f  tional result co
4f10: 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65  des that provide
4f20: 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69   more detailed i
4f30: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
4f40: 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73  out errors. Thes
4f50: 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  e [extended resu
4f60: 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e  lt codes] are en
4f70: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4f80: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4f90: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4fa0: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4fb0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4fc0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
4fd0: 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c  des()] API.  Or,
4fe0: 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f   the extended co
4ff0: 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f  de for.** the mo
5000: 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20  st recent error 
5010: 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
5020: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
5030: 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
5040: 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  de()]..*/.#defin
5050: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
5060: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
5070: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5080: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5090: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
50a0: 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20  ORT_READ        
50b0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
50c0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
50d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49  SQLITE_IOERR_WRI
50e0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  TE             (
50f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5100: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5110: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e  QLITE_IOERR_FSYN
5120: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  C             (S
5130: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34  QLITE_IOERR | (4
5140: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5150: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46  LITE_IOERR_DIR_F
5160: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51  SYNC         (SQ
5170: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c  LITE_IOERR | (5<
5180: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5190: 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41  ITE_IOERR_TRUNCA
51a0: 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TE          (SQL
51b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c  ITE_IOERR | (6<<
51c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51d0: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20  TE_IOERR_FSTAT  
51e0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
51f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38  TE_IOERR | (7<<8
5200: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5210: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20  E_IOERR_UNLOCK  
5220: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5230: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29  E_IOERR | (8<<8)
5240: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5250: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20  _IOERR_RDLOCK   
5260: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5270: 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29  _IOERR | (9<<8))
5280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5290: 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20  IOERR_DELETE    
52a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
52b0: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29  IOERR | (10<<8))
52c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52d0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20  IOERR_BLOCKED   
52e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
52f0: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29  IOERR | (11<<8))
5300: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5310: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20  IOERR_NOMEM     
5320: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5330: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29  IOERR | (12<<8))
5340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5350: 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20  IOERR_ACCESS    
5360: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5370: 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29  IOERR | (13<<8))
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5390: 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52  IOERR_CHECKRESER
53a0: 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f  VEDLOCK (SQLITE_
53b0: 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29  IOERR | (14<<8))
53c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53d0: 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20  IOERR_LOCK      
53e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
53f0: 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29  IOERR | (15<<8))
5400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5410: 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20  IOERR_CLOSE     
5420: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5430: 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29  IOERR | (16<<8))
5440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5450: 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20  IOERR_DIR_CLOSE 
5460: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5470: 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29  IOERR | (17<<8))
5480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5490: 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20  IOERR_SHMOPEN   
54a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
54b0: 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29  IOERR | (18<<8))
54c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54d0: 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20  IOERR_SHMSIZE   
54e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
54f0: 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29  IOERR | (19<<8))
5500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5510: 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20  IOERR_SHMLOCK   
5520: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5530: 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29  IOERR | (20<<8))
5540: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5550: 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20  IOERR_SHMMAP    
5560: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5570: 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29  IOERR | (21<<8))
5580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5590: 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20  IOERR_SEEK      
55a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
55b0: 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29  IOERR | (22<<8))
55c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55d0: 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45  IOERR_DELETE_NOE
55e0: 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  NT      (SQLITE_
55f0: 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29  IOERR | (23<<8))
5600: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5610: 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20  IOERR_MMAP      
5620: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5630: 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29  IOERR | (24<<8))
5640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5650: 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54  IOERR_GETTEMPPAT
5660: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
5670: 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29  IOERR | (25<<8))
5680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5690: 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20  IOERR_CONVPATH  
56a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56b0: 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29  IOERR | (26<<8))
56c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56d0: 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20 20  IOERR_VNODE     
56e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56f0: 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29 29  IOERR | (27<<8))
5700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5710: 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20 20 20  IOERR_AUTH      
5720: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5730: 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 29 29  IOERR | (28<<8))
5740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5750: 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43  LOCKED_SHAREDCAC
5760: 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  HE      (SQLITE_
5770: 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29  LOCKED |  (1<<8)
5780: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5790: 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20  _BUSY_RECOVERY  
57a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
57b0: 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38  _BUSY   |  (1<<8
57c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
57d0: 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20  E_BUSY_SNAPSHOT 
57e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
57f0: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c  E_BUSY   |  (2<<
5800: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5810: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45  TE_CANTOPEN_NOTE
5820: 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49  MPDIR      (SQLI
5830: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31  TE_CANTOPEN | (1
5840: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5850: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53  LITE_CANTOPEN_IS
5860: 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51  DIR          (SQ
5870: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5880: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5890: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
58a0: 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28  FULLPATH       (
58b0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
58c0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
58d0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
58e0: 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20  N_CONVPATH      
58f0: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5900: 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  N | (4<<8)).#def
5910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
5920: 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  PT_VTAB         
5930: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55     (SQLITE_CORRU
5940: 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  PT | (1<<8)).#de
5950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5960: 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20  ONLY_RECOVERY   
5970: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5980: 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23  ONLY | (1<<8)).#
5990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
59a0: 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20  ADONLY_CANTLOCK 
59b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
59c0: 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29  ADONLY | (2<<8))
59d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59e0: 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43  READONLY_ROLLBAC
59f0: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
5a00: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38  READONLY | (3<<8
5a10: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a20: 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56  E_READONLY_DBMOV
5a30: 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ED        (SQLIT
5a40: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c  E_READONLY | (4<
5a50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a60: 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41  ITE_ABORT_ROLLBA
5a70: 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  CK          (SQL
5a80: 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c  ITE_ABORT | (2<<
5a90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5aa0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48  TE_CONSTRAINT_CH
5ab0: 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49  ECK        (SQLI
5ac0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5ad0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5ae0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5af0: 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28  T_COMMITHOOK   (
5b00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b10: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
5b20: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5b30: 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59  RAINT_FOREIGNKEY
5b40: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5b50: 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a  RAINT | (3<<8)).
5b60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b70: 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49  ONSTRAINT_FUNCTI
5b80: 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  ON     (SQLITE_C
5b90: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c  ONSTRAINT | (4<<
5ba0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5bb0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f  TE_CONSTRAINT_NO
5bc0: 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49  TNULL      (SQLI
5bd0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5be0: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
5bf0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c00: 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28  T_PRIMARYKEY   (
5c10: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c20: 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  T | (6<<8)).#def
5c30: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5c40: 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20  RAINT_TRIGGER   
5c50: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5c60: 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a  RAINT | (7<<8)).
5c70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5c80: 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45  ONSTRAINT_UNIQUE
5c90: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5ca0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c  ONSTRAINT | (8<<
5cb0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5cc0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54  TE_CONSTRAINT_VT
5cd0: 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  AB         (SQLI
5ce0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5cf0: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5d00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5d10: 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28  T_ROWID        (
5d20: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5d30: 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66  T |(10<<8)).#def
5d40: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
5d50: 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20  E_RECOVER_WAL   
5d60: 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43     (SQLITE_NOTIC
5d70: 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  E | (1<<8)).#def
5d80: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
5d90: 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41  E_RECOVER_ROLLBA
5da0: 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43  CK (SQLITE_NOTIC
5db0: 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  E | (2<<8)).#def
5dc0: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
5dd0: 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20  NG_AUTOINDEX    
5de0: 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49     (SQLITE_WARNI
5df0: 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NG | (1<<8)).#de
5e00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
5e10: 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20  _USER           
5e20: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48      (SQLITE_AUTH
5e30: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5e40: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41  ne SQLITE_OK_LOA
5e50: 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20  D_PERMANENTLY   
5e60: 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28    (SQLITE_OK | (
5e70: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  1<<8))../*.** CA
5e80: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
5e90: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
5ea0: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
5eb0: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
5ec0: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
5ed0: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
5ee0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5ef0: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
5f00: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
5f10: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
5f20: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
5f30: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
5f40: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
5f50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f60: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
5f70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5f80: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
5f90: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5fa0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5fb0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
5fc0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5fd0: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
5fe0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ff0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6000: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
6010: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6020: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
6030: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6040: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6050: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
6060: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
6070: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
6080: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6090: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
60a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
60b0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
60c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60d0: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
60e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
60f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6100: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6110: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
6120: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
6130: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6140: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6150: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6160: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20  _OPEN_MEMORY    
6170: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
6180: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6190: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
61a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61b0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
61c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
61d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
61e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61f0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
6200: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6210: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6220: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6230: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
6240: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
6250: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6270: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
6280: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
6290: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
62a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62b0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
62c0: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
62d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
62e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62f0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
6300: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
6310: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6320: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6330: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
6340: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
6350: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6360: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6370: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
6380: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
6390: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
63a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
63b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
63c0: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
63d0: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
63e0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
63f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6400: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6410: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
6420: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
6430: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6440: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6450: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6460: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
6470: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
6480: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6490: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
64a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
64b0: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
64c0: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
64d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
64e0: 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20  /../* Reserved: 
64f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6500: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30          0x00F000
6510: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00 */../*.** CAP
6520: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
6530: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a  aracteristics.**
6540: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
6550: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
6560: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
6570: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6580: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
6590: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
65a0: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
65b0: 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74   of these.** bit
65c0: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69   values expressi
65d0: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72  ng I/O character
65e0: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61  istics of the ma
65f0: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65  ss storage.** de
6600: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20  vice that holds 
6610: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68  the file that th
6620: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6630: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73  thods].** refers
6640: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53   to..**.** The S
6650: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6660: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
6670: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
6680: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
6690: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
66a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
66b0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
66c0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
66d0: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
66e0: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
66f0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
6700: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
6710: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
6720: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
6730: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
6740: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6750: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6760: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
6770: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
6780: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
6790: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
67a0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
67b0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
67c0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
67d0: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
67e0: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
67f0: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
6800: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
6810: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6820: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6830: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
6840: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
6850: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
6860: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
6870: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
6880: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6890: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
68a0: 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79  ERWRITE property
68b0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61   means that.** a
68c0: 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c  fter reboot foll
68d0: 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72  owing a crash or
68e0: 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65   power loss, the
68f0: 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61   only bytes in a
6900: 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65  .** file that we
6910: 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68  re written at th
6920: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65  e application le
6930: 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63  vel might have c
6940: 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68  hanged.** and th
6950: 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65  at adjacent byte
6960: 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69  s, even bytes wi
6970: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65  thin the same se
6980: 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72  ctor are.** guar
6990: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63  anteed to be unc
69a0: 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c  hanged.  The SQL
69b0: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
69c0: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a  TABLE_WHEN_OPEN.
69d0: 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65  ** flag indicate
69e0: 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61  s that a file ca
69f0: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20  nnot be deleted 
6a00: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a  when open.  The.
6a10: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ** SQLITE_IOCAP_
6a20: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69  IMMUTABLE flag i
6a30: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
6a40: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20  e file is on.** 
6a50: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20  read-only media 
6a60: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  and cannot be ch
6a70: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72  anged even by pr
6a80: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20  ocesses with.** 
6a90: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65  elevated privile
6aa0: 67 65 73 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ges.  The SQLITE
6ab0: 5f 49 4f 43 41 50 5f 50 41 47 45 5f 50 45 52 5f  _IOCAP_PAGE_PER_
6ac0: 53 45 43 54 4f 52 20 66 6c 61 67 20 69 6e 64 69  SECTOR flag indi
6ad0: 63 61 74 65 73 0a 2a 2a 20 74 68 65 20 69 6e 69  cates.** the ini
6ae0: 74 69 61 6c 20 70 61 67 65 20 73 69 7a 65 20 66  tial page size f
6af0: 6f 72 20 6e 65 77 20 64 61 74 61 62 61 73 65 73  or new databases
6b00: 20 73 68 6f 75 6c 64 20 73 65 74 20 74 6f 20 74   should set to t
6b10: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 0a 2a  he sector size.*
6b20: 2a 20 72 65 70 6f 72 74 65 64 20 62 79 20 74 68  * reported by th
6b30: 65 20 56 46 53 2e 0a 2a 2f 0a 23 64 65 66 69 6e  e VFS..*/.#defin
6b40: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6b50: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20  TOMIC           
6b60: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
6b70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b80: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
6b90: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6ba0: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
6bb0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6bc0: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20  MIC1K           
6bd0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
6be0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6bf0: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20  CAP_ATOMIC2K    
6c00: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6c10: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
6c20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6c30: 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C4K             
6c40: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
6c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6c60: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20  P_ATOMIC8K      
6c70: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6c80: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
6c90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
6ca0: 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  6K              
6cb0: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
6cc0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6cd0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
6ce0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
6cf0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6d00: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
6d10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6d20: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
6d30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
6d40: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20  FE_APPEND       
6d50: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
6d60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6d70: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6d80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6d90: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
6da0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6db0: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6dc0: 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64  N  0x00000800.#d
6dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6de0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
6df0: 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30  RWRITE    0x0000
6e00: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  1000.#define SQL
6e10: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
6e20: 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  BLE             
6e30: 20 30 78 30 30 30 30 32 30 30 30 0a 23 64 65 66   0x00002000.#def
6e40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6e50: 5f 50 41 47 45 5f 50 45 52 5f 53 45 43 54 4f 52  _PAGE_PER_SECTOR
6e60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 34 30          0x000040
6e70: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
6e80: 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67  EF: File Locking
6e90: 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51   Levels.**.** SQ
6ea0: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
6eb0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
6ec0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
6ed0: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
6ee0: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
6ef0: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
6f00: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
6f10: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
6f20: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6f30: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
6f40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6f50: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
6f60: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
6f70: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
6f80: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
6f90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
6fa0: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
6fb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6fc0: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
6fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6fe0: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
6ff0: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
7000: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
7010: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a  tion Type Flags.
7020: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74  **.** When SQLit
7030: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
7040: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  ync() method of 
7050: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
7060: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
7070: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62  t it uses a comb
7080: 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68  ination of.** th
7090: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
70a0: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
70b0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
70c0: 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   When the SQLITE
70d0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66  _SYNC_DATAONLY f
70e0: 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20  lag is used, it 
70f0: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a  means that the.*
7100: 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  * sync operation
7110: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66   only needs to f
7120: 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73  lush data to mas
7130: 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64  s storage.  Inod
7140: 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
7150: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75   need not be flu
7160: 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77  shed. If the low
7170: 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20  er four bits of 
7180: 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61  the flag.** equa
7190: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  l SQLITE_SYNC_NO
71a0: 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  RMAL, that means
71b0: 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66   to use normal f
71c0: 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73  sync() semantics
71d0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65  ..** If the lowe
71e0: 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61  r four bits equa
71f0: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  l SQLITE_SYNC_FU
7200: 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  LL, that means.*
7210: 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20  * to use Mac OS 
7220: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
7230: 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e   instead of fsyn
7240: 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f  c()..**.** Do no
7250: 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51  t confuse the SQ
7260: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7270: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
7280: 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77  _FULL flags.** w
7290: 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20  ith the [PRAGMA 
72a0: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52  synchronous]=NOR
72b0: 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  MAL and [PRAGMA 
72c0: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c  synchronous]=FUL
72d0: 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20  L.** settings.  
72e0: 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73  The [synchronous
72f0: 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69   pragma] determi
7300: 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74  nes when calls t
7310: 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56  o the.** xSync V
7320: 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20  FS method occur 
7330: 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66  and applies unif
7340: 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c  ormly across all
7350: 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54   platforms..** T
7360: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
7370: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
7380: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
7390: 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a   determine how.*
73a0: 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72  * energetic or r
73b0: 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65  igorous or force
73c0: 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65  ful the sync ope
73d0: 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a  rations are and.
73e0: 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64  ** only make a d
73f0: 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63  ifference on Mac
7400: 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66   OSX for the def
7410: 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65  ault SQLite code
7420: 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74  ..** (Third-part
7430: 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  y VFS implementa
7440: 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f  tions might also
7450: 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
7460: 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e  ction.** between
7470: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
7480: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
7490: 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d  YNC_FULL, but am
74a0: 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61  ong the.** opera
74b0: 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74  ting systems nat
74c0: 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20  ively supported 
74d0: 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20  by SQLite, only 
74e0: 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73  Mac OSX.** cares
74f0: 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65   about the diffe
7500: 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69  rence.).*/.#defi
7510: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  ne SQLITE_SYNC_N
7520: 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30  ORMAL        0x0
7530: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
7540: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20  ITE_SYNC_FULL   
7550: 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23         0x00003.#
7560: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7570: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20  NC_DATAONLY     
7580: 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20   0x00010../*.** 
7590: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
75a0: 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65  erface Open File
75b0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e   Handle.**.** An
75c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
75d0: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
75e0: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
75f0: 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  n the .** [sqlit
7600: 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65  e3_vfs | OS inte
7610: 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49  rface layer].  I
7620: 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74  ndividual OS int
7630: 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d  erface.** implem
7640: 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a  entations will.*
7650: 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61  * want to subcla
7660: 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62  ss this object b
7670: 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69  y appending addi
7680: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
7690: 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75   for their own u
76a0: 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64  se.  The pMethod
76b0: 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69  s entry is a poi
76c0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
76d0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
76e0: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
76f0: 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66  efines methods f
7700: 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a  or performing.**
7710: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
7720: 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  on the open file
7730: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
7740: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
7750: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73   sqlite3_file;.s
7760: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
7770: 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72  le {.  const str
7780: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
7790: 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73  ethods *pMethods
77a0: 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f  ;  /* Methods fo
77b0: 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a  r an open file *
77c0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
77d0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
77e0: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20  ce File Virtual 
77f0: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a  Methods Object.*
7800: 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20  *.** Every file 
7810: 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73  opened by the [s
7820: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7830: 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74  ] method populat
7840: 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  es an.** [sqlite
7850: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28  3_file] object (
7860: 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c  or, more commonl
7870: 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66  y, a subclass of
7880: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
7890: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77  _file] object) w
78a0: 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ith a pointer to
78b0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
78c0: 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  this object..** 
78d0: 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  This object defi
78e0: 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20  nes the methods 
78f0: 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20  used to perform 
7900: 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f  various operatio
7910: 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68  ns.** against th
7920: 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72  e open file repr
7930: 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b  esented by the [
7940: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7950: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ject..**.** If t
7960: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7970: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65  xOpen] method se
7980: 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  ts the sqlite3_f
7990: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
79a0: 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f  ment .** to a no
79b0: 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
79c0: 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
79d0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f  _io_methods.xClo
79e0: 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79  se method.** may
79f0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e   be invoked even
7a00: 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   if the [sqlite3
7a10: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f  _vfs.xOpen] repo
7a20: 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69  rted that it fai
7a30: 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c  led.  The.** onl
7a40: 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74  y way to prevent
7a50: 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73   a call to xClos
7a60: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  e following a fa
7a70: 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66  iled [sqlite3_vf
7a80: 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66  s.xOpen].** is f
7a90: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
7aa0: 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65  vfs.xOpen] to se
7ab0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
7ac0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
7ad0: 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a  ent.** to NULL..
7ae0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
7af0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e  argument to xSyn
7b00: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  c may be one of 
7b10: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52  [SQLITE_SYNC_NOR
7b20: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  MAL] or.** [SQLI
7b30: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20  TE_SYNC_FULL].  
7b40: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65  The first choice
7b50: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66   is the normal f
7b60: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73  sync()..** The s
7b70: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20  econd choice is 
7b80: 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  a Mac OS X style
7b90: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20   fullsync.  The 
7ba0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54  [SQLITE_SYNC_DAT
7bb0: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d  AONLY].** flag m
7bc0: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f  ay be ORed in to
7bd0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f   indicate that o
7be0: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20  nly the data of 
7bf0: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20  the file.** and 
7c00: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65  not its inode ne
7c10: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64  eds to be synced
7c20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ..**.** The inte
7c30: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
7c40: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
7c50: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
7c60: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
7c70: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
7c80: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7c90: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
7ca0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7cb0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
7cc0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7cd0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
7ce0: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
7cf0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
7d00: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  E]..** </ul>.** 
7d10: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65  xLock() increase
7d20: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c  s the lock. xUnl
7d30: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20  ock() decreases 
7d40: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65  the lock..** The
7d50: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c   xCheckReservedL
7d60: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65  ock() method che
7d70: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20  cks whether any 
7d80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
7d90: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69  ion,.** either i
7da0: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f  n this process o
7db0: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
7dc0: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
7dd0: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a  ing a RESERVED,.
7de0: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45  ** PENDING, or E
7df0: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
7e00: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72   the file.  It r
7e10: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69  eturns true.** i
7e20: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78  f such a lock ex
7e30: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f  ists and false o
7e40: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
7e50: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  The xFileControl
7e60: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67  () method is a g
7e70: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65  eneric interface
7e80: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73   that allows cus
7e90: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65  tom.** VFS imple
7ea0: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69  mentations to di
7eb0: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61  rectly control a
7ec0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e  n open file usin
7ed0: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
7ee0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
7ef0: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  ] interface.  Th
7f00: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72  e second "op" ar
7f10: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20  gument is an.** 
7f20: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20  integer opcode. 
7f30: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
7f40: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63  ent is a generic
7f50: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65   pointer intende
7f60: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  d to.** point to
7f70: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61   a structure tha
7f80: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72  t may contain ar
7f90: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65  guments or space
7fa0: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20   in which to.** 
7fb0: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c  write return val
7fc0: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20  ues.  Potential 
7fd0: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f  uses for xFileCo
7fe0: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65  ntrol() might be
7ff0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  .** functions to
8000: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67   enable blocking
8010: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65   locks with time
8020: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20  outs, to change 
8030: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73  the.** locking s
8040: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61  trategy (for exa
8050: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d  mple to use dot-
8060: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20  file locks), to 
8070: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74  inquire.** about
8080: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61   the status of a
8090: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65   lock, or to bre
80a0: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20  ak stale locks. 
80b0: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63   The SQLite.** c
80c0: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c  ore reserves all
80d0: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68   opcodes less th
80e0: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f  an 100 for its o
80f0: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69  wn use..** A [fi
8100: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
8110: 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63  es | list of opc
8120: 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20  odes] less than 
8130: 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65  100 is available
8140: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
8150: 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20  s that define a 
8160: 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74  custom xFileCont
8170: 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  rol method shoul
8180: 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a  d use opcodes.**
8190: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30   greater than 10
81a0: 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c  0 to avoid confl
81b0: 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65  icts.  VFS imple
81c0: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
81d0: 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
81e0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f  ITE_NOTFOUND] fo
81f0: 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f  r file control o
8200: 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79  pcodes that they
8210: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67   do not.** recog
8220: 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nize..**.** The 
8230: 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65  xSectorSize() me
8240: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65  thod returns the
8250: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20   sector size of 
8260: 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  the.** device th
8270: 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65  at underlies the
8280: 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74   file.  The sect
8290: 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a  or size is the.*
82a0: 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20  * minimum write 
82b0: 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66  that can be perf
82c0: 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69  ormed without di
82d0: 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65  sturbing.** othe
82e0: 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  r bytes in the f
82f0: 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63  ile.  The xDevic
8300: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8310: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
8320: 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f  urns a bit vecto
8330: 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68  r describing beh
8340: 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a  aviors of the.**
8350: 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69   underlying devi
8360: 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ce:.**.** <ul>.*
8370: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8380: 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20  OCAP_ATOMIC].** 
8390: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
83a0: 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a  AP_ATOMIC512].**
83b0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
83c0: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a  CAP_ATOMIC1K].**
83d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
83e0: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a  CAP_ATOMIC2K].**
83f0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8400: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a  CAP_ATOMIC4K].**
8410: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8420: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a  CAP_ATOMIC8K].**
8430: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8440: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a  CAP_ATOMIC16K].*
8450: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8460: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a  OCAP_ATOMIC32K].
8470: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8480: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d  IOCAP_ATOMIC64K]
8490: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
84a0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
84b0: 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ND].** <li> [SQL
84c0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
84d0: 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  TIAL].** <li> [S
84e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
84f0: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
8500: 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  N].** <li> [SQLI
8510: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
8520: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 0a 2a 2a  FE_OVERWRITE].**
8530: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8540: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 0a 2a  CAP_IMMUTABLE].*
8550: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8560: 4f 43 41 50 5f 50 41 47 45 5f 50 45 52 5f 53 45  OCAP_PAGE_PER_SE
8570: 43 54 4f 52 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  CTOR].** </ul>.*
8580: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
8590: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
85a0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
85b0: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
85c0: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
85d0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
85e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
85f0: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
8600: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
8610: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
8620: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
8630: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
8640: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
8650: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
8660: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
8670: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
8680: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
8690: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
86a0: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
86b0: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
86c0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
86d0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
86e0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
86f0: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
8700: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
8710: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
8720: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
8730: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
8740: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8750: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
8760: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
8770: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
8780: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
8790: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
87a0: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
87b0: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
87c0: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
87d0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
87e0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
87f0: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
8800: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
8810: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
8820: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
8830: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
8840: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
8850: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8860: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
8870: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
8880: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
8890: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
88a0: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
88b0: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
88c0: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
88d0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
88e0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
88f0: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
8900: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
8910: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8920: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
8930: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
8940: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
8950: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8960: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
8970: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
8980: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
8990: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
89a0: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
89b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
89c0: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
89d0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
89e0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
89f0: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
8a00: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8a10: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
8a20: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
8a30: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8a40: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
8a50: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
8a60: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8a70: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
8a80: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
8a90: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8aa0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
8ab0: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
8ac0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
8ad0: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
8ae0: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
8af0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
8b00: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
8b10: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
8b20: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8b30: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
8b40: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
8b50: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
8b60: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
8b70: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8b80: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
8b90: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  le*);.  /* Metho
8ba0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8bb0: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31  id for version 1
8bc0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
8bd0: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  Map)(sqlite3_fil
8be0: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74  e*, int iPg, int
8bf0: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64   pgsz, int, void
8c00: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20   volatile**);.  
8c10: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28  int (*xShmLock)(
8c20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8c30: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e  nt offset, int n
8c40: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8c50: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69  void (*xShmBarri
8c60: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  er)(sqlite3_file
8c70: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8c80: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  Unmap)(sqlite3_f
8c90: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65  ile*, int delete
8ca0: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  Flag);.  /* Meth
8cb0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8cc0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8cd0: 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65  2 */.  int (*xFe
8ce0: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
8cf0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8d00: 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d  4 iOfst, int iAm
8d10: 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20  t, void **pp);. 
8d20: 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29   int (*xUnfetch)
8d30: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8d40: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
8d50: 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20  fst, void *p);. 
8d60: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8d70: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8d80: 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f  version 3 */.  /
8d90: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
8da0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
8db0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
8dc0: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
8dd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
8de0: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
8df0: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59  l Opcodes.** KEY
8e00: 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e  WORDS: {file con
8e10: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66  trol opcodes} {f
8e20: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
8e30: 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  de}.**.** These 
8e40: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
8e50: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
8e60: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
8e70: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
8e80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
8e90: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
8ea0: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
8eb0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8ec0: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
8ed0: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e..**.** <ul>.**
8ee0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8ef0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a  NTL_LOCKSTATE]].
8f00: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8f10: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
8f20: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
8f30: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
8f40: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
8f50: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
8f60: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
8f70: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
8f80: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
8f90: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
8fa0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
8fb0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
8fc0: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
8fd0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
8fe0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
8ff0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
9000: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
9010: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
9020: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
9030: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
9040: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
9050: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
9060: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
9070: 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c  sting and is onl
9080: 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e  y available when
9090: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54   the SQLITE_TEST
90a0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
90b0: 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
90c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
90d0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
90e0: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  INT]].** The [SQ
90f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9100: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20  HINT] opcode is 
9110: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74  used by SQLite t
9120: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a  o give the VFS.*
9130: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f  * layer a hint o
9140: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20  f how large the 
9150: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
9160: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75  ll grow to be du
9170: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72  ring the.** curr
9180: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  ent transaction.
9190: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e    This hint is n
91a0: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ot guaranteed to
91b0: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74   be accurate but
91c0: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20   it.** is often 
91d0: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65  close.  The unde
91e0: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74  rlying VFS might
91f0: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c   choose to preal
9200: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a  locate database.
9210: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61  ** file space ba
9220: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  sed on this hint
9230: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c   in order to hel
9240: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20  p writes to the 
9250: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
9260: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a   run faster..**.
9270: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9280: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
9290: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
92a0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
92b0: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ZE] opcode is us
92c0: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68  ed to request th
92d0: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78  at the VFS.** ex
92e0: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61  tends and trunca
92f0: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  tes the database
9300: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20   file in chunks 
9310: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66  of a size specif
9320: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73  ied.** by the us
9330: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61  er. The fourth a
9340: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
9350: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9360: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70  ()] should .** p
9370: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67  oint to an integ
9380: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f  er (type int) co
9390: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77  ntaining the new
93a0: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75   chunk-size to u
93b0: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f  se.** for the no
93c0: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65  minated database
93d0: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74  . Allocating dat
93e0: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65  abase file space
93f0: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75   in large.** chu
9400: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20  nks (say 1MB at 
9410: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64  a time), may red
9420: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20  uce file-system 
9430: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  fragmentation an
9440: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72  d.** improve per
9450: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65  formance on some
9460: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20   systems..**.** 
9470: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9480: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
9490: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
94a0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
94b0: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TER] opcode is u
94c0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20  sed to obtain a 
94d0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
94e0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
94f0: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74   object associat
9500: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ed with a partic
9510: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
9520: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
9530: 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46  e also [SQLITE_F
9540: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
9550: 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  NTER]..**.** <li
9560: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9570: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
9580: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9590: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
95a0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
95b0: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
95c0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
95d0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
95e0: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
95f0: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a  iated with the j
9600: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74  ournal file (eit
9610: 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c  her.** the [roll
9620: 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72  back journal] or
9630: 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61   the [write-ahea
9640: 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61  d log]) for a pa
9650: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
9660: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
9670: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49    See also [SQLI
9680: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9690: 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  INTER]..**.** <l
96a0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
96b0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
96c0: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20  ** No longer in 
96d0: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  use..**.** <li>[
96e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
96f0: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NC]].** The [SQL
9700: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20  ITE_FCNTL_SYNC] 
9710: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9720: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9730: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20  y SQLite and.** 
9740: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9750: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
9760: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  re the xSync met
9770: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hod is invoked o
9780: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  n a.** database 
9790: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e  file descriptor.
97a0: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e   Or, if the xSyn
97b0: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20  c method is not 
97c0: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61  invoked .** beca
97d0: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73  use the user has
97e0: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69   configured SQLi
97f0: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41  te with .** [PRA
9800: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20  GMA synchronous 
9810: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f  | PRAGMA synchro
9820: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20  nous=OFF] it is 
9830: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65  invoked in place
9840: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e   .** of the xSyn
9850: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73  c method. In mos
9860: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69  t cases, the poi
9870: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61  nter argument pa
9880: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69  ssed with.** thi
9890: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
98a0: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c  s NULL. However,
98b0: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
98c0: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73   file is being s
98d0: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  ynced.** as part
98e0: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61   of a multi-data
98f0: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65  base commit, the
9900: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
9910: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   to a nul-termin
9920: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63  ated.** string c
9930: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72  ontaining the tr
9940: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65  ansactions maste
9950: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e  r-journal file n
9960: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20  ame. VFSes that 
9970: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  .** do not need 
9980: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75  this signal shou
9990: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
99a0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
99b0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a  Applications .**
99c0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
99d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
99e0: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
99f0: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
9a00: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64  ing so may .** d
9a10: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
9a20: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9a30: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
9a40: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9a50: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
9a60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
9a70: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a  MIT_PHASETWO]].*
9a80: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9a90: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
9aa0: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TWO] opcode is g
9ab0: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
9ac0: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  lly by SQLite.**
9ad0: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65   and sent to the
9ae0: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61   VFS after a tra
9af0: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65  nsaction has bee
9b00: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65  n committed imme
9b10: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62  diately.** but b
9b20: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61  efore the databa
9b30: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20  se is unlocked. 
9b40: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  VFSes that do no
9b50: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9b60: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c  al.** should sil
9b70: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9b80: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9b90: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9ba0: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
9bb0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9bc0: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
9bd0: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
9be0: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
9bf0: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  .** operation of
9c00: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9c10: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
9c20: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
9c30: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9c40: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
9c50: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
9c60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9c70: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
9c80: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
9c90: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
9ca0: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
9cb0: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
9cc0: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
9cd0: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
9ce0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
9cf0: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
9d00: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
9d10: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
9d20: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
9d30: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
9d40: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
9d50: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
9d60: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
9d70: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
9d80: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
9d90: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
9da0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
9db0: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
9dc0: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
9dd0: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
9de0: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
9df0: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
9e00: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
9e10: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
9e20: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
9e30: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
9e40: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
9e50: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
9e60: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
9e70: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
9e80: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9e90: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
9ea0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
9eb0: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
9ec0: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
9ed0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
9ee0: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
9ef0: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
9f00: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
9f10: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9f20: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
9f30: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
9f40: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
9f50: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
9f60: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
9f70: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
9f80: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
9f90: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
9fa0: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
9fb0: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
9fc0: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
9fd0: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
9fe0: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
9ff0: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
a000: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
a010: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
a020: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
a030: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
a040: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
a050: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
a060: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
a070: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
a080: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a090: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
a0a0: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
a0b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
a0c0: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
a0d0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a0e0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a0f0: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
a100: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
a110: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
a120: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
a130: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
a140: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
a150: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
a160: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
a170: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
a180: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
a190: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
a1a0: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
a1b0: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
a1c0: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
a1d0: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
a1e0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
a1f0: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
a200: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
a210: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
a220: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
a230: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
a240: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
a250: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
a260: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
a270: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
a280: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
a290: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
a2a0: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
a2b0: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
a2c0: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
a2d0: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
a2e0: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
a2f0: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
a300: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
a310: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
a320: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
a330: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
a340: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a350: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
a360: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
a370: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
a380: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
a390: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
a3a0: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
a3b0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
a3c0: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
a3d0: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
a3e0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a3f0: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a400: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a410: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a420: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
a430: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
a440: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a450: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
a460: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
a470: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
a480: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
a490: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
a4a0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
a4b0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
a4c0: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
a4d0: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
a4e0: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
a4f0: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
a500: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
a510: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
a520: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
a530: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
a540: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
a550: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
a560: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
a570: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a580: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a590: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a5a0: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a5b0: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a5c0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a5d0: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a5e0: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a5f0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
a600: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a610: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
a620: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a630: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a640: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a650: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a660: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
a670: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
a680: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a690: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a6a0: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
a6b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
a6c0: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
a6d0: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
a6e0: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
a6f0: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
a700: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
a710: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
a720: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
a730: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
a740: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
a750: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
a760: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
a770: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
a780: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
a790: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
a7a0: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
a7b0: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
a7c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a7d0: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
a7e0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a7f0: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
a800: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
a810: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
a820: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
a830: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
a840: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
a850: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
a860: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
a870: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
a880: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
a890: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
a8a0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
a8b0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
a8c0: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
a8d0: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
a8e0: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a8f0: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
a900: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a910: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
a920: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
a930: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
a940: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
a950: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
a960: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
a970: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
a980: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
a990: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
a9a0: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
a9b0: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
a9c0: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
a9d0: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
a9e0: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
a9f0: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
aa00: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
aa10: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
aa20: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
aa30: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
aa40: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
aa50: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
aa60: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
aa70: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
aa80: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
aa90: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
aaa0: 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  FS_POINTER]].** 
aab0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
aac0: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20  TL_VFS_POINTER] 
aad0: 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70  opcode finds a p
aae0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f  ointer to the to
aaf0: 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65  p-level.** [VFSe
ab00: 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20  s] currently in 
ab10: 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75  use.  ^(The argu
ab20: 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c  ment X in.** sql
ab30: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
ab40: 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54  l(db,SQLITE_FCNT
ab50: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29  L_VFS_POINTER,X)
ab60: 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74   must be.** of t
ab70: 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66  ype "[sqlite3_vf
ab80: 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70  s] **".  This op
ab90: 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a  codes will set *
aba0: 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65  X.** to a pointe
abb0: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
abc0: 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68  el VFS.)^.** ^Wh
abd0: 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c  en there are mul
abe0: 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20  tiple VFS shims 
abf0: 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68  in the stack, th
ac00: 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20  is opcode finds 
ac10: 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73  the.** upper-mos
ac20: 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a  t shim only..**.
ac30: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ac40: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a  FCNTL_PRAGMA]].*
ac50: 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50  * ^Whenever a [P
ac60: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
ac70: 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b   is parsed, an [
ac80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ac90: 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f  GMA] .** file co
aca0: 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f  ntrol is sent to
acb0: 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74   the open [sqlit
acc0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
acd0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
ace0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
acf0: 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74   file to which t
ad00: 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  he pragma statem
ad10: 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65  ent refers. ^The
ad20: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
ad30: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
ad40: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
ad50: 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72  ontrol is an arr
ad60: 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72  ay of.** pointer
ad70: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68  s to strings (ch
ad80: 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74  ar**) in which t
ad90: 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e  he second elemen
ada0: 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a  t of the array.*
adb0: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
adc0: 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20   the pragma and 
add0: 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e  the third elemen
ade0: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
adf0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67  t to the.** prag
ae00: 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  ma or NULL if th
ae10: 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20  e pragma has no 
ae20: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20  argument.  ^The 
ae30: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a  handler for an.*
ae40: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
ae50: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
ae60: 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61  trol can optiona
ae70: 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72  lly make the fir
ae80: 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66  st element.** of
ae90: 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75   the char** argu
aea0: 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20  ment point to a 
aeb0: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
aec0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
aed0: 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74  rintf()].** or t
aee0: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  he equivalent an
aef0: 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69  d that string wi
af00: 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65  ll become the re
af10: 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67  sult of the prag
af20: 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72  ma or.** the err
af30: 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68  or message if th
af40: 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20  e pragma fails. 
af50: 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
af60: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
af70: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
af80: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f  turns [SQLITE_NO
af90: 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f  TFOUND], then no
afa0: 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  rmal .** [PRAGMA
afb0: 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e  ] processing con
afc0: 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65  tinues.  ^If the
afd0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
afe0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
aff0: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
b000: 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e  SQLITE_OK], then
b010: 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75   the parser assu
b020: 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
b030: 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20  VFS has handled 
b040: 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c  the PRAGMA itsel
b050: 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72  f and the parser
b060: 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d   generates a no-
b070: 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  op.** prepared s
b080: 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75  tatement if resu
b090: 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c  lt string is NUL
b0a0: 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72  L, or that retur
b0b0: 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  ns a copy.** of 
b0c0: 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e  the result strin
b0d0: 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  g if the string 
b0e0: 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20  is non-NULL..** 
b0f0: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
b100: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
b110: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
b120: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74  ns.** any result
b130: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e   code other than
b140: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
b150: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
b160: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  ], that means.**
b170: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e   that the VFS en
b180: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72  countered an err
b190: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e  or while handlin
b1a0: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61  g the [PRAGMA] a
b1b0: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  nd the.** compil
b1c0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41  ation of the PRA
b1d0: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61  GMA fails with a
b1e0: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b  n error.  ^The [
b1f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b200: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
b210: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74  trol occurs at t
b220: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
b230: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
b240: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f   analysis and so
b250: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74  .** it is able t
b260: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74  o override built
b270: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  -in [PRAGMA] sta
b280: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c  tements..**.** <
b290: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b2a0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a  L_BUSYHANDLER]].
b2b0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
b2c0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
b2d0: 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  R].** file-contr
b2e0: 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ol may be invoke
b2f0: 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74  d by SQLite on t
b300: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
b310: 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74   handle.** short
b320: 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f  ly after it is o
b330: 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  pened in order t
b340: 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74  o provide a cust
b350: 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65  om VFS with acce
b360: 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e  ss.** to the con
b370: 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61  nections busy-ha
b380: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  ndler callback. 
b390: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
b3a0: 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a  of type (void **
b3b0: 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20  ).** - an array 
b3c0: 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20  of two (void *) 
b3d0: 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73  values. The firs
b3e0: 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61  t (void *) actua
b3f0: 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f  lly points.** to
b400: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
b410: 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69  ype (int (*)(voi
b420: 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20  d *)). In order 
b430: 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f  to invoke the co
b440: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73  nnections.** bus
b450: 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20  y-handler, this 
b460: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
b470: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
b480: 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64  the second (void
b490: 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72   *) in.** the ar
b4a0: 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ray as the only 
b4b0: 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20  argument. If it 
b4c0: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
b4d0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61  , then the opera
b4e0: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
b4f0: 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74  e retried. If it
b500: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
b510: 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68  he custom VFS sh
b520: 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65  ould abandon the
b530: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72  .** current oper
b540: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
b550: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b560: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a  TEMPFILENAME]].*
b570: 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63  * ^Application c
b580: 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53  an invoke the [S
b590: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
b5a0: 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63  FILENAME] file-c
b5b0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76  ontrol.** to hav
b5c0: 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74  e SQLite generat
b5d0: 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  e a.** temporary
b5e0: 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20   filename using 
b5f0: 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
b600: 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f  hm that is follo
b610: 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a  wed to generate.
b620: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
b630: 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20  enames for TEMP 
b640: 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72  tables and other
b650: 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20   internal uses. 
b660: 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   The.** argument
b670: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61   should be a cha
b680: 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62  r** which will b
b690: 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  e filled with th
b6a0: 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72  e filename.** wr
b6b0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
b6c0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
b6d0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
b6e0: 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20  )].  The caller 
b6f0: 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65  should.** invoke
b700: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
b710: 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20  ] on the result 
b720: 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72  to avoid a memor
b730: 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  y leak..**.** <l
b740: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b750: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
b760: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b770: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
b780: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e control is use
b790: 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65  d to query or se
b7a0: 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d  t the.** maximum
b7b0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
b7c0: 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73   that will be us
b7d0: 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61  ed for memory-ma
b7e0: 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65  pped I/O..** The
b7f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
b800: 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75  ointer to a valu
b810: 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65  e of type sqlite
b820: 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20  3_int64 that.** 
b830: 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d  is an advisory m
b840: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
b850: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
b860: 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70  le to memory map
b870: 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  .  The.** pointe
b880: 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  r is overwritten
b890: 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61   with the old va
b8a0: 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20  lue.  The limit 
b8b0: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69  is not changed i
b8c0: 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f  f.** the value o
b8d0: 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65  riginally pointe
b8e0: 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65  d to is negative
b8f0: 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72  , and so the cur
b900: 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63  rent limit .** c
b910: 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79  an be queried by
b920: 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f   passing in a po
b930: 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74  inter to a negat
b940: 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69  ive number.  Thi
b950: 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  s.** file-contro
b960: 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  l is used intern
b970: 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  ally to implemen
b980: 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  t [PRAGMA mmap_s
b990: 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ize]..**.** <li>
b9a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b9b0: 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  RACE]].** The [S
b9c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
b9d0: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
b9e0: 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72  provides advisor
b9f0: 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  y information.**
ba00: 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75   to the VFS abou
ba10: 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65  t what the highe
ba20: 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20  r layers of the 
ba30: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65  SQLite stack are
ba40: 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20   doing..** This 
ba50: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
ba60: 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53  used by some VFS
ba70: 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e   activity tracin
ba80: 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68  g [shims]..** Th
ba90: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
baa0: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
bab0: 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20  string.  Higher 
bac0: 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a  layers in the.**
bad0: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61   SQLite stack ma
bae0: 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61  y generate insta
baf0: 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c  nces of this fil
bb00: 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20  e control if.** 
bb10: 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
bb20: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d  FCNTL_TRACE] com
bb30: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
bb40: 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
bb50: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
bb60: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
bb70: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
bb80: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
bb90: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
bba0: 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72  nterprets its ar
bbb0: 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70  gument as a.** p
bbc0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
bbd0: 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74  eger and it writ
bbe0: 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74  es a boolean int
bbf0: 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64  o that integer d
bc00: 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77  epending.** on w
bc10: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
bc20: 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20  e file has been 
bc30: 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20  renamed, moved, 
bc40: 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65  or deleted since
bc50: 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74   it.** was first
bc60: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c   opened..**.** <
bc70: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bc80: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44  L_WIN32_GET_HAND
bc90: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  LE]].** The [SQL
bca0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
bcb0: 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f  GET_HANDLE] opco
bcc0: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
bcd0: 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a 20  o obtain the.** 
bce0: 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69 76  underlying nativ
bcf0: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 73  e file handle as
bd00: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
bd10: 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54 68  file handle.  Th
bd20: 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72  is file.** contr
bd30: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
bd40: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 20  s argument as a 
bd50: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61 74  pointer to a nat
bd60: 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  ive file handle 
bd70: 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74 68  and.** writes th
bd80: 65 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c 75  e resulting valu
bd90: 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c  e there..**.** <
bda0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bdb0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
bdc0: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  LE]].** The [SQL
bdd0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
bde0: 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f  SET_HANDLE] opco
bdf0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
be00: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
be10: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
be20: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
be30: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70  l method to swap
be40: 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65   the file handle
be50: 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a   with the one.**
be60: 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
be70: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
be80: 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  .  This capabili
be90: 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ty is used durin
bea0: 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64  g testing.** and
beb0: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
bec0: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
bed0: 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20   SQLITE_TEST is 
bee0: 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
bef0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bf00: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a  L_WAL_BLOCK]].**
bf10: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
bf20: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73  TL_WAL_BLOCK] is
bf30: 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65   a signal to the
bf40: 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20   VFS layer that 
bf50: 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61  it might.** be a
bf60: 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62  dvantageous to b
bf70: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74  lock on the next
bf80: 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65   WAL lock if the
bf90: 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d   lock is not imm
bfa0: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69  ediately.** avai
bfb0: 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20  lable.  The WAL 
bfc0: 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73  subsystem issues
bfd0: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72   this signal dur
bfe0: 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63  ing rare.** circ
bff0: 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64  umstances in ord
c000: 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62  er to fix a prob
c010: 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74  lem with priorit
c020: 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20  y inversion..** 
c030: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
c040: 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e  uld <em>not</em>
c050: 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63   use this file-c
c060: 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ontrol..**.** <l
c070: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c080: 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65  _ZIPVFS]].** The
c090: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a   [SQLITE_FCNTL_Z
c0a0: 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73  IPVFS] opcode is
c0b0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
c0c0: 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c  zipvfs only. All
c0d0: 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68   other.** VFS sh
c0e0: 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49  ould return SQLI
c0f0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20  TE_NOTFOUND for 
c100: 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a  this opcode..**.
c110: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c120: 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54  FCNTL_RBU]].** T
c130: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c140: 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20  _RBU] opcode is 
c150: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74  implemented by t
c160: 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75  he special VFS u
c170: 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42  sed by.** the RB
c180: 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79  U extension only
c190: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53  .  All other VFS
c1a0: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53   should return S
c1b0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66  QLITE_NOTFOUND f
c1c0: 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64  or.** this opcod
c1d0: 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  e.  .**.** <li>[
c1e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 41  [SQLITE_FCNTL_PA
c1f0: 47 45 5f 50 45 52 5f 53 45 43 54 4f 52 5d 5d 0a  GE_PER_SECTOR]].
c200: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
c210: 46 43 4e 54 4c 5f 50 41 47 45 5f 50 45 52 5f 53  FCNTL_PAGE_PER_S
c220: 45 43 54 4f 52 5d 20 6f 70 63 6f 64 65 20 69 73  ECTOR] opcode is
c230: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
c240: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
c250: 73 69 73 74 65 6e 74 20 22 70 61 67 65 2d 70 65  sistent "page-pe
c260: 72 2d 73 65 63 74 6f 72 22 20 6f 72 20 22 50 50  r-sector" or "PP
c270: 53 22 20 73 65 74 74 69 6e 67 2e 20 54 68 65 20  S" setting. The 
c280: 50 50 53 20 73 65 74 74 69 6e 67 20 64 65 74 65  PPS setting dete
c290: 72 6d 69 6e 65 73 0a 2a 2a 20 74 68 65 20 5b 53  rmines.** the [S
c2a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 41 47 45  QLITE_IOCAP_PAGE
c2b0: 5f 50 45 52 5f 53 45 43 54 4f 52 5d 20 62 69 74  _PER_SECTOR] bit
c2c0: 20 6f 66 20 74 68 65 20 78 44 65 76 69 63 65 43   of the xDeviceC
c2d0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
c2e0: 2a 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66  * methods. The f
c2f0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
c300: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  to [sqlite3_file
c310: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
c320: 74 68 69 73 20 6f 70 63 6f 64 65 0a 2a 2a 20 73  this opcode.** s
c330: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
c340: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
c350: 2e 20 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  .  That integer 
c360: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 0a  is 0 to disable.
c370: 2a 2a 20 70 61 67 65 2d 70 65 72 2d 73 65 63 74  ** page-per-sect
c380: 6f 72 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  or mode or 1 to 
c390: 65 6e 61 62 6c 65 20 70 61 67 65 2d 70 65 72 2d  enable page-per-
c3a0: 73 65 63 74 6f 72 20 6d 6f 64 65 2e 20 20 49 66  sector mode.  If
c3b0: 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
c3c0: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
c3d0: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
c3e0: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 20 70  th the current p
c3f0: 61 67 65 2d 70 65 72 2d 73 65 63 74 6f 72 20 6d  age-per-sector m
c400: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 20  ode setting..** 
c410: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
c420: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
c430: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
c440: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
c450: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
c460: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
c470: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
c480: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
c490: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
c4a0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
c4b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
c4c0: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
c4d0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
c4e0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
c4f0: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
c500: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
c510: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
c520: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
c530: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
c540: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
c550: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
c560: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
c570: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
c580: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
c590: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c5a0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
c5b0: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
c5c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c5d0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
c5e0: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
c5f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c600: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
c610: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
c620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c630: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
c640: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
c650: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c660: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
c670: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
c680: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c690: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
c6a0: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
c6b0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c6c0: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
c6d0: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
c6e0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
c6f0: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
c700: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65        16.#define
c710: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d   SQLITE_FCNTL_MM
c720: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  AP_SIZE         
c730: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20       18.#define 
c740: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
c750: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CE              
c760: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53      19.#define S
c770: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
c780: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20  MOVED           
c790: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51     20.#define SQ
c7a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20  LITE_FCNTL_SYNC 
c7b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c7c0: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    21.#define SQL
c7d0: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
c7e0: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20  _PHASETWO       
c7f0: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   22.#define SQLI
c800: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
c810: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
c820: 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  23.#define SQLIT
c830: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
c840: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  K              2
c850: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
c860: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20  _FCNTL_ZIPVFS   
c870: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
c880: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c890: 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20  FCNTL_RBU       
c8a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a               26.
c8b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c8c0: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
c8d0: 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a 23              27.#
c8e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c8f0: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e  NTL_JOURNAL_POIN
c900: 54 45 52 20 20 20 20 20 20 20 20 32 38 0a 23 64  TER        28.#d
c910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c920: 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e  TL_WIN32_GET_HAN
c930: 44 4c 45 20 20 20 20 20 20 20 32 39 0a 23 64 65  DLE       29.#de
c940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c950: 4c 5f 50 44 42 20 20 20 20 20 20 20 20 20 20 20  L_PDB           
c960: 20 20 20 20 20 20 20 20 20 33 30 0a 23 64 65 66           30.#def
c970: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c980: 5f 50 41 47 45 5f 50 45 52 5f 53 45 43 54 4f 52  _PAGE_PER_SECTOR
c990: 20 20 20 20 20 20 20 20 33 31 0a 0a 2f 2a 20 64          31../* d
c9a0: 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20  eprecated names 
c9b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c9c0: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
c9d0: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f  ILE      SQLITE_
c9e0: 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52  FCNTL_GET_LOCKPR
c9f0: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20  OXYFILE.#define 
ca00: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
ca10: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
ca20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c  LITE_FCNTL_SET_L
ca30: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
ca40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
ca50: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
ca60: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
ca70: 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a  LAST_ERRNO.../*.
ca80: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
ca90: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
caa0: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
cab0: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
cac0: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
cad0: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
cae0: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
caf0: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
cb00: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
cb10: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
cb20: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
cb30: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
cb40: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
cb50: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
cb60: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
cb70: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
cb80: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
cb90: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
cba0: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
cbb0: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
cbc0: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
cbd0: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
cbe0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
cbf0: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
cc00: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
cc10: 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65  F: Loadable Exte
cc20: 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a  nsion Thunk.**.*
cc30: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
cc40: 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65  he opaque sqlite
cc50: 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73  3_api_routines s
cc60: 74 72 75 63 74 75 72 65 20 69 73 20 70 61 73 73  tructure is pass
cc70: 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69  ed as.** the thi
cc80: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
cc90: 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20  entry points of 
cca0: 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73  [loadable extens
ccb0: 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20  ions].  This.** 
ccc0: 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 62  structure must b
ccd0: 65 20 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f  e typedefed in o
cce0: 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f  rder to work aro
ccf0: 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72  und compiler war
cd00: 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65  nings.** on some
cd10: 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74   platforms..*/.t
cd20: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
cd30: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
cd40: 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  es sqlite3_api_r
cd50: 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20  outines;../*.** 
cd60: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
cd70: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  erface Object.**
cd80: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
cd90: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
cda0: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  fs object define
cdb0: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
cdc0: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53  between.** the S
cdd0: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74  QLite core and t
cde0: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
cdf0: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
ce00: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e   The "vfs".** in
ce10: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
ce20: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66   object stands f
ce30: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65  or "virtual file
ce40: 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a   system".  See.*
ce50: 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53  * the [VFS | VFS
ce60: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
ce70: 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f  for further info
ce80: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
ce90: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
cea0: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69  iVersion field i
ceb0: 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75  s initially 1 bu
cec0: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20  t may be larger 
ced0: 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72  in.** future ver
cee0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
cef0: 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65    Additional fie
cf00: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
cf10: 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f  ded to this.** o
cf20: 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69  bject when the i
cf30: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73  Version value is
cf40: 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74   increased.  Not
cf50: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63  e that the struc
cf60: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73  ture.** of the s
cf70: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
cf80: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  t changes in the
cf90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74   transaction bet
cfa0: 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76  ween.** SQLite v
cfb0: 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64  ersion 3.5.9 and
cfc0: 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74   3.6.0 and yet t
cfd0: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
cfe0: 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64  d was not.** mod
cff0: 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ified..**.** The
d000: 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20   szOsFile field 
d010: 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
d020: 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73  he subclassed [s
d030: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20  qlite3_file].** 
d040: 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62  structure used b
d050: 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50  y this VFS.  mxP
d060: 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d  athname is the m
d070: 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
d080: 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69  .** a pathname i
d090: 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a  n this VFS..**.*
d0a0: 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c  * Registered sql
d0b0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73  ite3_vfs objects
d0c0: 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c   are kept on a l
d0d0: 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65  inked list forme
d0e0: 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78  d by.** the pNex
d0f0: 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  t pointer.  The 
d100: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67  [sqlite3_vfs_reg
d110: 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20  ister()].** and 
d120: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72  [sqlite3_vfs_unr
d130: 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72  egister()] inter
d140: 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69  faces manage thi
d150: 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74  s list.** in a t
d160: 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20  hread-safe way. 
d170: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
d180: 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66  s_find()] interf
d190: 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20  ace.** searches 
d1a0: 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68  the list.  Neith
d1b0: 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
d1c0: 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20  on code nor the 
d1d0: 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  VFS.** implement
d1e0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ation should use
d1f0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
d200: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e  er..**.** The pN
d210: 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65  ext field is the
d220: 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74   only field in t
d230: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
d240: 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  * structure that
d250: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65   SQLite will eve
d260: 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74  r modify.  SQLit
d270: 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65  e will only acce
d280: 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20  ss.** or modify 
d290: 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65  this field while
d2a0: 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69   holding a parti
d2b0: 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74  cular static mut
d2c0: 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ex..** The appli
d2d0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
d2e0: 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68  ver modify anyth
d2f0: 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73  ing within the s
d300: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62  qlite3_vfs.** ob
d310: 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62  ject once the ob
d320: 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65  ject has been re
d330: 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  gistered..**.** 
d340: 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20  The zName field 
d350: 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f  holds the name o
d360: 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65  f the VFS module
d370: 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74  .  The name must
d380: 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63  .** be unique ac
d390: 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64  ross all VFS mod
d3a0: 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  ules..**.** [[sq
d3b0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
d3c0: 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ].** ^SQLite gua
d3d0: 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
d3e0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
d3f0: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a  eter to xOpen.**
d400: 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c   is either a NUL
d410: 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72  L pointer or str
d420: 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ing obtained.** 
d430: 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61  from xFullPathna
d440: 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74  me() with an opt
d450: 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64  ional suffix add
d460: 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66  ed..** ^If a suf
d470: 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20  fix is added to 
d480: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
d490: 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c  rameter, it will
d4a0: 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61  .** consist of a
d4b0: 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72   single "-" char
d4c0: 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62  acter followed b
d4d0: 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a  y no more than.*
d4e0: 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69  * 11 alphanumeri
d4f0: 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61  c and/or "-" cha
d500: 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c  racters..** ^SQL
d510: 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72  ite further guar
d520: 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74  antees that.** t
d530: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
d540: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
d550: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
d560: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
d570: 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  d. Because of th
d580: 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
d590: 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  nce,.** the [sql
d5a0: 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73  ite3_file] can s
d5b0: 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f  afely store a po
d5c0: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
d5d0: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e  filename if it n
d5e0: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72  eeds to remember
d5f0: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f   the filename fo
d600: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a  r some reason..*
d610: 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61  * If the zFilena
d620: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
d630: 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20  xOpen is a NULL 
d640: 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70  pointer then xOp
d650: 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e  en.** must inven
d660: 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72  t its own tempor
d670: 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65  ary name for the
d680: 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65   file.  ^Wheneve
d690: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e  r the .** xFilen
d6a0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
d6b0: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c   NULL it will al
d6c0: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74  so be the case t
d6d0: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73  hat the.** flags
d6e0: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20   parameter will 
d6f0: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
d700: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
d710: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  SE]..**.** The f
d720: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
d730: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
d740: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
d750: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
d760: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
d770: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
d780: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
d790: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
d7a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
d7b0: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
d7c0: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
d7d0: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
d7e0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
d7f0: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
d800: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66  _CREATE]. .** If
d810: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
d820: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
d830: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
d840: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
d850: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
d860: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
d870: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
d880: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73  utFlags may be s
d890: 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69  et..**.** ^(SQLi
d8a0: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
d8b0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
d8c0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
d8d0: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
d8e0: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
d8f0: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
d900: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20  g opened:.**.** 
d910: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ul>.** <li>  [S
d920: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
d930: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
d940: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
d950: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
d960: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
d970: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  MP_DB].** <li>  
d980: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
d990: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  P_JOURNAL].** <l
d9a0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d9b0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a  _TRANSIENT_DB].*
d9c0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d9d0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d  OPEN_SUBJOURNAL]
d9e0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
d9f0: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
da00: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
da10: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c  [SQLITE_OPEN_WAL
da20: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  ].** </ul>)^.**.
da30: 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20  ** The file I/O 
da40: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63  implementation c
da50: 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63  an use the objec
da60: 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a  t type flags to.
da70: 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61  ** change the wa
da80: 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20  y it deals with 
da90: 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d  files.  For exam
daa0: 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
dab0: 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73  ion.** that does
dac0: 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20   not care about 
dad0: 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f  crash recovery o
dae0: 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74  r rollback might
daf0: 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65   make.** the ope
db00: 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66  n of a journal f
db10: 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72  ile a no-op.  Wr
db20: 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75  ites to this jou
db30: 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c  rnal would.** al
db40: 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e  so be no-ops, an
db50: 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  d any attempt to
db60: 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61   read the journa
db70: 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a  l would return.*
db80: 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20  * SQLITE_IOERR. 
db90: 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   Or the implemen
dba0: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63  tation might rec
dbb0: 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61  ognize that a da
dbc0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77  tabase.** file w
dbd0: 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67  ill be doing pag
dbe0: 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72  e-aligned sector
dbf0: 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65   reads and write
dc00: 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a  s in a random.**
dc10: 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75   order and set u
dc20: 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73  p its I/O subsys
dc30: 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e  tem accordingly.
dc40: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69  .**.** SQLite mi
dc50: 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ght also add one
dc60: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
dc70: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
dc80: 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Open method:.**.
dc90: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
dca0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
dcb0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c  ETEONCLOSE].** <
dcc0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
dcd0: 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c  _EXCLUSIVE].** <
dce0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  /ul>.**.** The [
dcf0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
dd00: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
dd10: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
dd20: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
dd30: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
dd40: 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51  losed.  ^The [SQ
dd50: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
dd60: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
dd70: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
dd80: 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74   databases and t
dd90: 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74  heir journals, t
dda0: 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61  ransient.** data
ddb0: 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f  bases, and subjo
ddc0: 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  urnals..**.** ^T
ddd0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
dde0: 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20  EXCLUSIVE] flag 
ddf0: 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69  is always used i
de00: 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a  n conjunction.**
de10: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
de20: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66  E_OPEN_CREATE] f
de30: 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62  lag, which are b
de40: 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  oth directly.** 
de50: 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65  analogous to the
de60: 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52   O_EXCL and O_CR
de70: 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65  EAT flags of the
de80: 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a   POSIX open().**
de90: 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54   API.  The SQLIT
dea0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
deb0: 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72   flag, when pair
dec0: 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
ded0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
dee0: 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69  TE, is used to i
def0: 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c  ndicate that fil
df00: 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a  e should always.
df10: 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61  ** be created, a
df20: 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e  nd that it is an
df30: 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72   error if it alr
df40: 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20  eady exists..** 
df50: 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e  It is <i>not</i>
df60: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
df70: 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  e the file shoul
df80: 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20  d be opened .** 
df90: 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63  for exclusive ac
dfa0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20  cess..**.** ^At 
dfb0: 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62  least szOsFile b
dfc0: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ytes of memory a
dfd0: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
dfe0: 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c  SQLite.** to hol
dff0: 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
e000: 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
e010: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
e020: 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ird.** argument 
e030: 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78  to xOpen.  The x
e040: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
e050: 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
e060: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
e070: 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
e080: 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
e090: 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a  n.  Note that.**
e0a0: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
e0b0: 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73  d must set the s
e0c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
e0d0: 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a  hods to either.*
e0e0: 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74  * a valid [sqlit
e0f0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
e100: 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c  bject or to NULL
e110: 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f  .  xOpen must do
e120: 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66  .** this even if
e130: 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e   the open fails.
e140: 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73    SQLite expects
e150: 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65   that the sqlite
e160: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a  3_file.pMethods.
e170: 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20  ** element will 
e180: 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78  be valid after x
e190: 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67  Open returns reg
e1a0: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73  ardless of the s
e1b0: 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69  uccess.** or fai
e1c0: 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65  lure of the xOpe
e1d0: 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  n call..**.** [[
e1e0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63  sqlite3_vfs.xAcc
e1f0: 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c  ess]].** ^The fl
e200: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
e210: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
e220: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
e230: 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65  EXISTS].** to te
e240: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
e250: 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20  ence of a file, 
e260: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
e270: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a  S_READWRITE] to.
e280: 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20  ** test whether 
e290: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
e2a0: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
e2b0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
e2c0: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
e2d0: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
e2e0: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
e2f0: 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66  eadable.   The f
e300: 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20  ile can be a.** 
e310: 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
e320: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c   ^SQLite will al
e330: 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74  ways allocate at
e340: 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d   least mxPathnam
e350: 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68  e+1 bytes for th
e360: 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66  e.** output buff
e370: 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  er xFullPathname
e380: 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a  .  The exact siz
e390: 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20  e of the output 
e3a0: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73  buffer.** is als
e3b0: 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61  o passed as a pa
e3c0: 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20  rameter to both 
e3d0: 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65   methods. If the
e3e0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
e3f0: 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65  * is not large e
e400: 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43  nough, [SQLITE_C
e410: 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20  ANTOPEN] should 
e420: 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e  be returned. Sin
e430: 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61  ce this is.** ha
e440: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
e450: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
e460: 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61  , vfs implementa
e470: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64  tions should end
e480: 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76  eavor.** to prev
e490: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
e4a0: 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74  ing mxPathname t
e4b0: 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79  o a sufficiently
e4c0: 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a   large value..**
e4d0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
e4e0: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
e4f0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c   xCurrentTime(),
e500: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
e510: 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65  eInt64().** inte
e520: 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73  rfaces are not s
e530: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f  trictly a part o
e540: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d  f the filesystem
e550: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a  , but they are.*
e560: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  * included in th
e570: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20  e VFS structure 
e580: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73  for completeness
e590: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  ..** The xRandom
e5a0: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  ness() function 
e5b0: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75  attempts to retu
e5c0: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  rn nBytes bytes.
e5d0: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69  ** of good-quali
e5e0: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  ty randomness in
e5f0: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65  to zOut.  The re
e600: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a  turn value is.**
e610: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62   the actual numb
e620: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72  er of bytes of r
e630: 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
e640: 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65  ed..** The xSlee
e650: 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65  p() method cause
e660: 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  s the calling th
e670: 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f  read to sleep fo
e680: 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68  r at.** least th
e690: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72  e number of micr
e6a0: 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20  oseconds given. 
e6b0: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
e6c0: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
e6d0: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
e6e0: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
e6f0: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
e700: 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61  and time as.** a
e710: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
e720: 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78  value..** ^The x
e730: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
e740: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
e750: 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72  s, as an integer
e760: 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20  , the Julian.** 
e770: 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69  Day Number multi
e780: 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30  plied by 8640000
e790: 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  0 (the number of
e7a0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e   milliseconds in
e7b0: 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64   .** a 24-hour d
e7c0: 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74  ay).  .** ^SQLit
e7d0: 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78  e will use the x
e7e0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
e7f0: 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74  () method to get
e800: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
e810: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66  date and time if
e820: 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20   that method is 
e830: 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56  available (if iV
e840: 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a  ersion is 2 or .
e850: 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74  ** greater and t
e860: 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
e870: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29  ter is not NULL)
e880: 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62   and will fall b
e890: 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65  ack.** to xCurre
e8a0: 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72  ntTime() if xCur
e8b0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
e8c0: 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
e8d0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53  **.** ^The xSetS
e8e0: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65  ystemCall(), xGe
e8f0: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61  tSystemCall(), a
e900: 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61  nd xNestSystemCa
e910: 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  ll() interfaces.
e920: 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20  ** are not used 
e930: 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  by the SQLite co
e940: 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f  re.  These optio
e950: 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  nal interfaces a
e960: 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62  re provided.** b
e970: 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20  y some VFSes to 
e980: 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69  facilitate testi
e990: 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f  ng of the VFS co
e9a0: 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e  de. By overridin
e9b0: 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c  g .** system cal
e9c0: 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e  ls with function
e9d0: 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74  s under its cont
e9e0: 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67  rol, a test prog
e9f0: 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c  ram can.** simul
ea00: 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65  ate faults and e
ea10: 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20  rror conditions 
ea20: 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72  that would other
ea30: 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c  wise be difficul
ea40: 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62  t.** or impossib
ea50: 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54  le to induce.  T
ea60: 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d  he set of system
ea70: 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20   calls that can 
ea80: 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a  be overridden.**
ea90: 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65   varies from one
eaa0: 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c   VFS to another,
eab0: 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65   and from one ve
eac0: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d  rsion of the sam
ead0: 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20  e VFS to the.** 
eae0: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
eaf0: 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65  ons that use the
eb00: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75  se interfaces mu
eb10: 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66  st be prepared f
eb20: 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c  or any.** or all
eb30: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66   of these interf
eb40: 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20  aces to be NULL 
eb50: 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68  or for their beh
eb60: 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a  avior to change.
eb70: 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65  ** from one rele
eb80: 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ase to the next.
eb90: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d    Applications m
eba0: 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20  ust not attempt 
ebb0: 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79  to access.** any
ebc0: 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64   of these method
ebd0: 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f  s if the iVersio
ebe0: 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20  n of the VFS is 
ebf0: 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a  less than 3..*/.
ec00: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
ec10: 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74  qlite3_vfs sqlit
ec20: 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20  e3_vfs;.typedef 
ec30: 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73  void (*sqlite3_s
ec40: 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64  yscall_ptr)(void
ec50: 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  );.struct sqlite
ec60: 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56  3_vfs {.  int iV
ec70: 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20  ersion;         
ec80: 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20     /* Structure 
ec90: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28  version number (
eca0: 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a  currently 3) */.
ecb0: 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20    int szOsFile; 
ecc0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69             /* Si
ecd0: 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64  ze of subclassed
ece0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f   sqlite3_file */
ecf0: 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d  .  int mxPathnam
ed00: 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  e;          /* M
ed10: 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68  aximum file path
ed20: 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20  name length */. 
ed30: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e   sqlite3_vfs *pN
ed40: 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78  ext;      /* Nex
ed50: 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53  t registered VFS
ed60: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
ed70: 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f   *zName;       /
ed80: 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76  * Name of this v
ed90: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
eda0: 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  em */.  void *pA
edb0: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
edc0: 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61   /* Pointer to a
edd0: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69  pplication-speci
ede0: 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e  fic data */.  in
edf0: 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
ee00: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
ee10: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
ee20: 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20  te3_file*,.     
ee30: 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c            int fl
ee40: 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c  ags, int *pOutFl
ee50: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  ags);.  int (*xD
ee60: 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76  elete)(sqlite3_v
ee70: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
ee80: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63  *zName, int sync
ee90: 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41  Dir);.  int (*xA
eea0: 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  ccess)(sqlite3_v
eeb0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
eec0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67  *zName, int flag
eed0: 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  s, int *pResOut)
eee0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50  ;.  int (*xFullP
eef0: 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  athname)(sqlite3
ef00: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ef10: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f  r *zName, int nO
ef20: 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ut, char *zOut);
ef30: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70  .  void *(*xDlOp
ef40: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
ef50: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
ef60: 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64  ilename);.  void
ef70: 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c   (*xDlError)(sql
ef80: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
ef90: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72  Byte, char *zErr
efa0: 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28  Msg);.  void (*(
efb0: 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33  *xDlSym)(sqlite3
efc0: 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e  _vfs*,void*, con
efd0: 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c  st char *zSymbol
efe0: 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64  ))(void);.  void
eff0: 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c   (*xDlClose)(sql
f000: 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a  ite3_vfs*, void*
f010: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64  );.  int (*xRand
f020: 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f  omness)(sqlite3_
f030: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
f040: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
f050: 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71  int (*xSleep)(sq
f060: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
f070: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20  microseconds);. 
f080: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
f090: 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ime)(sqlite3_vfs
f0a0: 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69  *, double*);.  i
f0b0: 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72  nt (*xGetLastErr
f0c0: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
f0d0: 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a  , int, char *);.
f0e0: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
f0f0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
f100: 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20  in version 1 of 
f110: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
f120: 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e  bject.  ** defin
f130: 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68  ition.  Those th
f140: 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64  at follow are ad
f150: 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32  ded in version 2
f160: 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20   or later.  */. 
f170: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
f180: 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65  imeInt64)(sqlite
f190: 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f  3_vfs*, sqlite3_
f1a0: 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20  int64*);.  /*.  
f1b0: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
f1c0: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
f1d0: 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20  ions 1 and 2 of 
f1e0: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
f1f0: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73  bject..  ** Thos
f200: 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20  e below are for 
f210: 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72  version 3 and gr
f220: 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e  eater..  */.  in
f230: 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61  t (*xSetSystemCa
f240: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
f250: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
f260: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73  ame, sqlite3_sys
f270: 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c  call_ptr);.  sql
f280: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
f290: 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c   (*xGetSystemCal
f2a0: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
f2b0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
f2c0: 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61  me);.  const cha
f2d0: 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d  r *(*xNextSystem
f2e0: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
f2f0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
f300: 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a  zName);.  /*.  *
f310: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
f320: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
f330: 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20  ons 1 through 3 
f340: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
f350: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e  s object..  ** N
f360: 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  ew fields may be
f370: 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 75 74   appended in fut
f380: 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54  ure versions.  T
f390: 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a  he iVersion.  **
f3a0: 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72   value will incr
f3b0: 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74  ement whenever t
f3c0: 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20  his happens. .  
f3d0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
f3e0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
f3f0: 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53   the xAccess VFS
f400: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
f410: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
f420: 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65  tants can be use
f430: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70  d as the third p
f440: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
f450: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
f460: 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  d of an [sqlite3
f470: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  _vfs] object.  T
f480: 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hey determine.**
f490: 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65   what kind of pe
f4a0: 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41  rmissions the xA
f4b0: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20  ccess method is 
f4c0: 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20  looking for..** 
f4d0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
f4e0: 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78  SS_EXISTS, the x
f4f0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
f500: 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77   simply checks w
f510: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
f520: 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20  exists..** With 
f530: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
f540: 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63  ADWRITE, the xAc
f550: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
f560: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
f570: 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72  e named director
f580: 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62  y is both readab
f590: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a  le and writable.
f5a0: 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72  ** (in other wor
f5b0: 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e  ds, if files can
f5c0: 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76   be added, remov
f5d0: 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20  ed, and renamed 
f5e0: 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69  within.** the di
f5f0: 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65  rectory)..** The
f600: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
f610: 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e  EADWRITE constan
f620: 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75  t is currently u
f630: 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a  sed only by the.
f640: 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  ** [temp_store_d
f650: 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
f660: 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f  , though this co
f670: 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20  uld change in a 
f680: 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73  future.** releas
f690: 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  e of SQLite..** 
f6a0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
f6b0: 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63  SS_READ, the xAc
f6c0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
f6d0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
f6e0: 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  e file is readab
f6f0: 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  le.  The SQLITE_
f700: 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73  ACCESS_READ cons
f710: 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65  tant is.** curre
f720: 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f  ntly unused, tho
f730: 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20  ugh it might be 
f740: 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65  used in a future
f750: 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
f760: 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
f770: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
f780: 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66  EXISTS    0.#def
f790: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
f7a0: 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20  S_READWRITE 1   
f7b0: 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d  /* Used by PRAGM
f7c0: 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72  A temp_store_dir
f7d0: 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e  ectory */.#defin
f7e0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
f7f0: 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a  READ      2   /*
f800: 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a   Unused */../*.*
f810: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
f820: 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f  s for the xShmLo
f830: 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ck VFS method.**
f840: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
f850: 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  r constants defi
f860: 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  ne the various l
f870: 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e  ocking operation
f880: 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20  s.** allowed by 
f890: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  the xShmLock met
f8a0: 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  hod of [sqlite3_
f8b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68  io_methods].  Th
f8c0: 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  e.** following a
f8d0: 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61  re the only lega
f8e0: 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f  l combinations o
f8f0: 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a  f flags to the.*
f900: 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  * xShmLock metho
f910: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
f920: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f930: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
f940: 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
f950: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
f960: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
f970: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c  _EXCLUSIVE.** <l
f980: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
f990: 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
f9a0: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
f9b0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
f9c0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
f9d0: 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
f9e0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  /ul>.**.** When 
f9f0: 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73  unlocking, the s
fa00: 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58  ame SHARED or EX
fa10: 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73  CLUSIVE flag mus
fa20: 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73  t be supplied as
fa30: 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e  .** was given on
fa40: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
fa50: 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a  ng lock.  .**.**
fa60: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
fa70: 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74  thod can transit
fa80: 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  ion between unlo
fa90: 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20  cked and SHARED 
faa0: 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e  or.** between un
fab0: 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55  locked and EXCLU
fac0: 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74  SIVE.  It cannot
fad0: 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
fae0: 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e  een SHARED.** an
faf0: 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a  d EXCLUSIVE..*/.
fb00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
fb10: 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  HM_UNLOCK       
fb20: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
fb30: 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20  _SHM_LOCK       
fb40: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
fb50: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20  TE_SHM_SHARED   
fb60: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
fb70: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
fb80: 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43  VE    8../*.** C
fb90: 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d  API3REF: Maximum
fba0: 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a   xShmLock index.
fbb0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
fbc0: 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71  ck method on [sq
fbd0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
fbe0: 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73  ] may use values
fbf0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
fc00: 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75  d this upper bou
fc10: 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65  nd as its "offse
fc20: 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  t" argument..** 
fc30: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
fc40: 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d  will never attem
fc50: 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72  pt to acquire or
fc60: 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f   release a.** lo
fc70: 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  ck outside of th
fc80: 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66  is range.*/.#def
fc90: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e  ine SQLITE_SHM_N
fca0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a  LOCK        8...
fcb0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
fcc0: 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53  Initialize The S
fcd0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
fce0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
fcf0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
fd00: 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65  utine initialize
fd10: 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  s the.** SQLite 
fd20: 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73  library.  ^The s
fd30: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fd40: 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61  ) routine.** dea
fd50: 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73  llocates any res
fd60: 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65  ources that were
fd70: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
fd80: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fd90: 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ()..** These rou
fda0: 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e  tines are design
fdb0: 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f  ed to aid in pro
fdc0: 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
fdd0: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64  ion and.** shutd
fde0: 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20  own on embedded 
fdf0: 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74  systems.  Workst
fe00: 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f  ation applicatio
fe10: 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69  ns using.** SQLi
fe20: 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e  te normally do n
fe30: 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b  ot need to invok
fe40: 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73  e either of thes
fe50: 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
fe60: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
fe70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fe80: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
fe90: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
fea0: 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69  .** the first ti
feb0: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
fec0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
fed0: 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69  ed during the li
fee0: 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65  fetime of.** the
fef0: 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
ff00: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  it is the first 
ff10: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
ff20: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
ff30: 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  oked.** followin
ff40: 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  g a call to sqli
ff50: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
ff60: 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63   ^(Only an effec
ff70: 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20  tive call.** of 
ff80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ff90: 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e  ze() does any in
ffa0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41  itialization.  A
ffb0: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a  ll other calls.*
ffc0: 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  * are harmless n
ffd0: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  o-ops.)^.**.** A
ffe0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
fff0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61  _shutdown() is a
10000 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
10010 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20  ll if it is the 
10020 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f  first.** call to
10030 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10040 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61  n() since the la
10050 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  st sqlite3_initi
10060 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79  alize().  ^(Only
10070 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65  .** an effective
10080 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
10090 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73  _shutdown() does
100a0 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a   any deinitializ
100b0 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74  ation..** All ot
100c0 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20  her valid calls 
100d0 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
100e0 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65  own() are harmle
100f0 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
10100 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
10110 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65  nitialize() inte
10120 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73  rface is threads
10130 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33  afe, but sqlite3
10140 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69  _shutdown().** i
10150 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69  s not.  The sqli
10160 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
10170 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e  nterface must on
10180 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  ly be called fro
10190 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68  m a.** single th
101a0 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20  read.  All open 
101b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
101c0 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63  tions] must be c
101d0 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a  losed and all.**
101e0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65   other SQLite re
101f0 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20  sources must be 
10200 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f  deallocated prio
10210 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a  r to invoking.**
10220 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10230 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67  n()..**.** Among
10240 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e   other things, ^
10250 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10260 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ze() will invoke
10270 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
10280 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c  nit().  Similarl
10290 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74  y, ^sqlite3_shut
102a0 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69  down().** will i
102b0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73  nvoke sqlite3_os
102c0 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  _end()..**.** ^T
102d0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
102e0 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
102f0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
10300 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a  OK] on success..
10310 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20  ** ^If for some 
10320 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  reason, sqlite3_
10330 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
10340 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61  unable to initia
10350 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72  lize.** the libr
10360 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20  ary (perhaps it 
10370 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
10380 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72  ocate a needed r
10390 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20  esource such.** 
103a0 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72  as a mutex) it r
103b0 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72  eturns an [error
103c0 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61   code] other tha
103d0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  n [SQLITE_OK]..*
103e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
103f0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
10400 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
10410 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d   internally by m
10420 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  any other.** SQL
10430 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73  ite interfaces s
10440 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63  o that an applic
10450 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f  ation usually do
10460 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a  es not need to.*
10470 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
10480 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
10490 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61  rectly.  For exa
104a0 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  mple, [sqlite3_o
104b0 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20  pen()].** calls 
104c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
104d0 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69  ze() so the SQLi
104e0 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
104f0 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
10500 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  .** initialized 
10510 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70  when [sqlite3_op
10520 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  en()] is called 
10530 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65  if it has not be
10540 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20   initialized.** 
10550 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76  already.  ^Howev
10560 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73  er, if SQLite is
10570 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
10580 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
10590 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d  AUTOINIT].** com
105a0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
105b0 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d  , then the autom
105c0 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71  atic calls to sq
105d0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
105e0 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65  ().** are omitte
105f0 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  d and the applic
10600 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20  ation must call 
10610 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10620 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a  ze() directly.**
10630 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
10640 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
10650 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72   interface.  For
10660 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69   maximum portabi
10670 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72  lity,.** it is r
10680 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
10690 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77  applications alw
106a0 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ays invoke sqlit
106b0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
106c0 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f  ** directly prio
106d0 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
106e0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
106f0 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72  rface.  Future r
10700 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51  eleases.** of SQ
10710 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65  Lite may require
10720 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72   this.  In other
10730 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61   words, the beha
10740 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a  vior exhibited.*
10750 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
10760 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
10770 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
10780 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f  INIT] might beco
10790 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c  me the.** defaul
107a0 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f  t behavior in so
107b0 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
107c0 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  e of SQLite..**.
107d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
107e0 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65  s_init() routine
107f0 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d   does operating-
10800 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a  system specific.
10810 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ** initializatio
10820 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  n of the SQLite 
10830 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71  library.  The sq
10840 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
10850 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73  * routine undoes
10860 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73   the effect of s
10870 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10880 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73  .  Typical tasks
10890 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79  .** performed by
108a0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
108b0 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69  include allocati
108c0 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69  on or deallocati
108d0 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20  on.** of static 
108e0 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69  resources, initi
108f0 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f  alization of glo
10900 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a  bal variables,.*
10910 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64  * setting up a d
10920 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
10930 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20  vfs] module, or 
10940 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20  setting up.** a 
10950 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
10960 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c  ation using [sql
10970 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a  ite3_config()]..
10980 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
10990 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
109a0 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  er invoke either
109b0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
109c0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
109d0 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74  _os_end() direct
109e0 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  ly.  The applica
109f0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  tion should only
10a00 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
10a10 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10a20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74  and sqlite3_shut
10a30 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c  down().  The sql
10a40 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
10a50 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63  * interface is c
10a60 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61  alled automatica
10a70 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69  lly by sqlite3_i
10a80 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a  nitialize() and.
10a90 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ** sqlite3_os_en
10aa0 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79  d() is called by
10ab0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10ac0 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74  n().  Appropriat
10ad0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
10ae0 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33  ions for sqlite3
10af0 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
10b00 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
10b10 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74  ** are built int
10b20 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74  o SQLite when it
10b30 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72   is compiled for
10b40 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20   Unix, Windows, 
10b50 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e  or OS/2..** When
10b60 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20   [custom builds 
10b70 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65  | built for othe
10b80 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20  r platforms].** 
10b90 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49  (using the [SQLI
10ba0 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63  TE_OS_OTHER=1] c
10bb0 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
10bc0 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69  ption) the appli
10bd0 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70  cation must supp
10be0 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d  ly a suitable im
10bf0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  plementation for
10c00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
10c10 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
10c20 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20  3_os_end().  An 
10c30 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
10c40 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  lied.** implemen
10c50 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
10c60 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73  3_os_init() or s
10c70 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
10c80 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b  ** must return [
10c90 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
10ca0 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f  ccess and some o
10cb0 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65  ther [error code
10cc0 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72  ] upon.** failur
10cd0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
10ce0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69  3_initialize(voi
10cf0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
10d00 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a  shutdown(void);.
10d10 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  int sqlite3_os_i
10d20 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  nit(void);.int s
10d30 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f  qlite3_os_end(vo
10d40 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
10d50 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e  3REF: Configurin
10d60 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  g The SQLite Lib
10d70 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rary.**.** The s
10d80 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10d90 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
10da0 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c  d to make global
10db0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
10dc0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c  * changes to SQL
10dd0 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
10de0 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74  tune SQLite to t
10df0 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
10e00 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  s of.** the appl
10e10 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  ication.  The de
10e20 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
10e30 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ion is recommend
10e40 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61  ed for most.** a
10e50 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20  pplications and 
10e60 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  so this routine 
10e70 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e  is usually not n
10e80 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73  ecessary.  It is
10e90 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20  .** provided to 
10ea0 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70  support rare app
10eb0 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75  lications with u
10ec0 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a  nusual needs..**
10ed0 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74  .** <b>The sqlit
10ee0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
10ef0 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
10f00 65 61 64 73 61 66 65 2e 20 54 68 65 20 61 70 70  eadsafe. The app
10f10 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
10f20 20 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   ensure that no 
10f30 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
10f40 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
10f50 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
10f60 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
10f70 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10f80 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a  s running.</b>.*
10f90 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
10fa0 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
10fb0 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ace.** may only 
10fc0 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72  be invoked prior
10fd0 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74   to library init
10fe0 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67  ialization using
10ff0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  .** [sqlite3_ini
11000 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  tialize()] or af
11010 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20  ter shutdown by 
11020 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
11030 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  n()]..** ^If sql
11040 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
11050 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
11060 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11070 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a  e()] and before.
11080 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
11090 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20  down()] then it 
110a0 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  will return SQLI
110b0 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f  TE_MISUSE..** No
110c0 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61  te, however, tha
110d0 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t ^sqlite3_confi
110e0 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  g() can be calle
110f0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
11100 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
11110 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61  on of an applica
11120 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71  tion-defined [sq
11130 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d  lite3_os_init()]
11140 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
11150 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  t argument to sq
11160 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
11170 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
11180 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
11190 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
111a0 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
111b0 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
111c0 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
111d0 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
111e0 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
111f0 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
11200 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61  n the [configura
11210 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20  tion option].** 
11220 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
11230 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  ument..**.** ^Wh
11240 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69  en a configurati
11250 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  on option is set
11260 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
11270 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  () returns [SQLI
11280 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74  TE_OK]..** ^If t
11290 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b  he option is unk
112a0 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69  nown or SQLite i
112b0 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20  s unable to set 
112c0 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68  the option.** th
112d0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
112e0 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65  returns a non-ze
112f0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ro [error code].
11300 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
11310 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29  config(int, ...)
11320 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11330 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74  F: Configure dat
11340 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11350 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
11360 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite3.**.** The s
11370 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
11380 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
11390 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
113a0 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
113b0 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
113c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
113d0 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
113e0 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
113f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
11400 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
11410 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
11420 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
11430 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
11440 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
11450 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
11460 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
11470 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
11480 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
11490 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
114a0 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
114b0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
114c0 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
114d0 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
114e0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
114f0 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
11500 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
11510 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
11520 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
11530 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
11540 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
11550 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
11560 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
11570 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
11580 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
11590 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
115a0 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
115b0 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
115c0 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
115d0 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
115e0 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
115f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
11600 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
11610 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
11620 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11630 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
11640 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
11650 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
11660 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
11670 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
11680 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
11690 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
116a0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
116b0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
116c0 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
116d0 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
116e0 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
116f0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
11700 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
11710 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
11720 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
11730 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
11740 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
11750 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
11760 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11770 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
11780 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
11790 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
117a0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
117b0 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
117c0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
117d0 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
117e0 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
117f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11800 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
11810 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
11820 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
11830 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
11840 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
11850 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
11860 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11870 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
11880 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
11890 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
118a0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
118b0 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
118c0 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
118d0 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
118e0 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
118f0 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
11900 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
11910 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
11920 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
11930 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
11940 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
11950 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
11960 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
11970 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
11980 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
11990 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
119a0 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
119b0 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
119c0 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
119d0 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
119e0 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
119f0 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
11a00 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
11a10 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
11a20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
11a30 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
11a40 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
11a50 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
11a60 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
11a70 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
11a80 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
11a90 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
11aa0 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
11ab0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
11ac0 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
11ad0 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
11ae0 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
11af0 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
11b00 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
11b10 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
11b20 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
11b30 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
11b40 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
11b50 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
11b60 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
11b70 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
11b80 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
11b90 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
11ba0 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
11bb0 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
11bc0 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
11bd0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
11be0 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
11bf0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
11c00 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
11c10 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
11c20 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
11c30 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
11c40 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
11c50 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
11c60 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
11c70 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
11c80 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
11c90 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
11ca0 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
11cb0 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
11cc0 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
11cd0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11ce0 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
11cf0 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
11d00 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
11d10 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
11d20 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
11d30 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
11d40 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
11d50 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
11d60 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
11d70 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
11d80 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
11d90 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
11da0 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
11db0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
11dc0 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
11dd0 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
11de0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
11df0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
11e00 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
11e10 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
11e20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
11e30 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
11e40 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
11e50 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
11e60 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
11e70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
11e80 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
11e90 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
11ea0 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65  llocator.  For e
11eb0 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69  xample,.** it mi
11ec0 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79  ght allocate any
11ed0 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73   require mutexes
11ee0 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69   or initialize i
11ef0 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20  nternal data.** 
11f00 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65  structures.  The
11f10 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
11f20 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e  d is invoked (in
11f30 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20  directly) by.** 
11f40 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
11f50 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20  n()] and should 
11f60 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  deallocate any r
11f70 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65  esources acquire
11f80 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20  d.** by xInit.  
11f90 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69  The pAppData poi
11fa0 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20  nter is used as 
11fb0 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
11fc0 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61  er to.** xInit a
11fd0 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a  nd xShutdown..**
11fe0 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73  .** SQLite holds
11ff0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
12000 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
12010 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20  ] mutex when it 
12020 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78  invokes.** the x
12030 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20  Init method, so 
12040 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
12050 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72   need not be thr
12060 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a  eadsafe.  The.**
12070 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
12080 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64  d is only called
12090 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
120a0 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74  hutdown()] so it
120b0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65   does.** not nee
120c0 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61  d to be threadsa
120d0 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20  fe either.  For 
120e0 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64  all other method
120f0 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c  s, SQLite.** hol
12100 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
12110 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d  UTEX_STATIC_MEM]
12120 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61   mutex as long a
12130 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
12140 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
12150 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  S] configuration
12160 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65   option is turne
12170 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69  d on (which.** i
12180 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29  t is by default)
12190 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68   and so the meth
121a0 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69  ods are automati
121b0 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64  cally serialized
121c0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66  ..** However, if
121d0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
121e0 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69  MEMSTATUS] is di
121f0 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  sabled, then the
12200 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64   other.** method
12210 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  s must be thread
12220 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b  safe or else mak
12230 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61  e their own arra
12240 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20  ngements for.** 
12250 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  serialization..*
12260 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  *.** SQLite will
12270 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49   never invoke xI
12280 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20  nit() more than 
12290 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20  once without an 
122a0 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63  intervening.** c
122b0 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e  all to xShutdown
122c0 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ()..*/.typedef s
122d0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
122e0 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  m_methods sqlite
122f0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73  3_mem_methods;.s
12300 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
12310 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f  m_methods {.  vo
12320 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69  id *(*xMalloc)(i
12330 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20  nt);         /* 
12340 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
12350 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  n function */.  
12360 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f  void (*xFree)(vo
12370 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f  id*);          /
12380 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61  * Free a prior a
12390 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76  llocation */.  v
123a0 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29  oid *(*xRealloc)
123b0 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a  (void*,int);  /*
123c0 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63   Resize an alloc
123d0 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
123e0 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20  *xSize)(void*); 
123f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74            /* Ret
12400 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  urn the size of 
12410 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
12420 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75  .  int (*xRoundu
12430 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  p)(int);        
12440 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65    /* Round up re
12450 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c  quest size to al
12460 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f  location size */
12470 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28  .  int (*xInit)(
12480 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
12490 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20    /* Initialize 
124a0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
124b0 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28  ator */.  void (
124c0 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64  *xShutdown)(void
124d0 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e  *);      /* Dein
124e0 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
124f0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
12500 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
12510 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  a;              
12520 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f    /* Argument to
12530 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68   xInit() and xSh
12540 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a  utdown() */.};..
12550 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12560 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
12570 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
12580 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f  S: {configuratio
12590 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20  n option}.**.** 
125a0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
125b0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
125c0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
125d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
125e0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
125f0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
12600 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
12610 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
12620 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
12630 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
12640 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
12650 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
12660 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
12670 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
12680 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
12690 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
126a0 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
126b0 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
126c0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
126d0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
126e0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
126f0 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
12700 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
12710 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
12720 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
12730 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
12740 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
12750 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
12760 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
12770 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
12780 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
12790 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
127a0 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
127b0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
127c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
127d0 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  GLETHREAD]] <dt>
127e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
127f0 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a  NGLETHREAD</dt>.
12800 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
12810 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
12820 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
12830 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
12840 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
12850 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67  ng mode] to Sing
12860 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  le-thread.  In o
12870 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
12880 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  isables.** all m
12890 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73  utexing and puts
128a0 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d   SQLite into a m
128b0 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e  ode where it can
128c0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a   only be used.**
128d0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
128e0 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ead.   ^If SQLit
128f0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12900 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
12910 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
12920 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12930 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
12940 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
12950 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
12960 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  le to change the
12970 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12980 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75  ] from its defau
12990 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53  lt.** value of S
129a0 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64  ingle-thread and
129b0 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   so [sqlite3_con
129c0 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
129d0 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rn .** [SQLITE_E
129e0 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
129f0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
12a00 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
12a10 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  EAD.** configura
12a20 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
12a30 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12a40 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
12a50 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
12a60 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
12a70 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
12a80 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
12a90 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
12aa0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
12ab0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
12ac0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12ad0 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61  ] to Multi-threa
12ae0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
12af0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
12b00 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
12b10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12b20 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
12b30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
12b40 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
12b50 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
12b60 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
12b70 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
12b80 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
12b90 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
12ba0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12bb0 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
12bc0 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
12bd0 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
12be0 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
12bf0 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
12c00 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
12c10 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  .** environment 
12c20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
12c30 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70  o threads attemp
12c40 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  t to use the sam
12c50 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
12c60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68  onnection] at th
12c70 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49  e same time.  ^I
12c80 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
12c90 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
12ca0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
12cb0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
12cc0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
12cd0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
12ce0 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
12cf0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
12d00 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61   the Multi-threa
12d10 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
12d20 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
12d30 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
12d40 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
12d50 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
12d60 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
12d70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
12d80 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72  ITHREAD configur
12d90 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
12da0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12db0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
12dc0 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ZED]] <dt>SQLITE
12dd0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
12de0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
12df0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
12e00 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
12e10 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
12e20 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
12e30 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
12e40 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20   to Serialized. 
12e50 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
12e60 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62  this option enab
12e70 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
12e80 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65  es including the
12e90 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75   recursive.** mu
12ea0 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61  texes on [databa
12eb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
12ec0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
12ed0 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
12ee0 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65  .** In this mode
12ef0 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64   (which is the d
12f00 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69  efault when SQLi
12f10 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
12f20 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  ith.** [SQLITE_T
12f30 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68  HREADSAFE=1]) th
12f40 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
12f50 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72   will itself ser
12f60 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a  ialize access.**
12f70 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f   to [database co
12f80 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
12f90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12fa0 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65  nts] so that the
12fb0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
12fc0 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74  is free to use t
12fd0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
12fe0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72  e connection] or
12ff0 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72   the.** same [pr
13000 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
13010 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74  ] in different t
13020 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
13030 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20  me time..** ^If 
13040 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13050 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13060 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13070 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13080 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13090 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
130a0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
130b0 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
130c0 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74  he Serialized [t
130d0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
130e0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
130f0 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
13100 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
13110 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
13120 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
13130 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
13140 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ED configuration
13150 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
13160 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13170 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  FIG_MALLOC]] <dt
13180 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
13190 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
131a0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
131b0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70  CONFIG_MALLOC op
131c0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
131d0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
131e0 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  ch is .** a poin
131f0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
13200 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
13210 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
13220 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
13230 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
13240 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
13250 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  ive low-level me
13260 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13270 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
13280 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a  sed in place of.
13290 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
132a0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
132b0 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
132c0 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d  ite.)^ ^SQLite m
132d0 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20  akes.** its own 
132e0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
132f0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
13300 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
13310 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13320 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65  re.** before the
13330 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13340 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  ()] call returns
13350 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13360 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13370 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
13380 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
13390 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
133a0 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
133b0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
133c0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
133d0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
133e0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
133f0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
13400 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
13410 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
13420 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
13430 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
13440 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
13450 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
13460 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
13470 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72  ly defined memor
13480 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
13490 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
134a0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
134b0 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
134c0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
134d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
134e0 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
134f0 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
13500 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
13510 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
13520 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
13530 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
13540 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64  or example. </dd
13550 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13560 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
13570 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  S]] <dt>SQLITE_C
13580 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
13590 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
135a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
135b0 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e  MEMSTATUS option
135c0 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
135d0 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
135e0 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  nt,.** interpret
135f0 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c  ed as a boolean,
13600 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
13610 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
13620 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20  ollection of.** 
13630 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13640 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  n statistics. ^(
13650 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
13660 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
13670 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
13680 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  d, the following
13690 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
136a0 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70  es become non-op
136b0 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20  erational:.**   
136c0 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  <ul>.**   <li> [
136d0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
136e0 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  sed()].**   <li>
136f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
13700 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a  _highwater()].**
13710 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
13720 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
13730 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  64()].**   <li> 
13740 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36  [sqlite3_status6
13750 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29  4()].**   </ul>)
13760 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c  ^.** ^Memory all
13770 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
13780 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  cs are enabled b
13790 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73  y default unless
137a0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
137b0 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
137c0 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
137d0 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63  TATUS]=0 in whic
137e0 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a  h case memory.**
137f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
13800 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
13810 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
13820 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
13830 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
13840 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c  CRATCH]] <dt>SQL
13850 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
13860 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
13870 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
13880 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f  IG_SCRATCH optio
13890 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
138a0 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
138b0 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  er.** that SQLit
138c0 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63  e can use for sc
138d0 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e  ratch memory.  ^
138e0 28 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  (There are three
138f0 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f   arguments.** to
13900 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
13910 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74  CRATCH:  A point
13920 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  er an 8-byte.** 
13930 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
13940 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68  uffer from which
13950 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c   the scratch all
13960 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65  ocations will be
13970 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73  .** drawn, the s
13980 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61  ize of each scra
13990 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28  tch allocation (
139a0 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20  sz),.** and the 
139b0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
139c0 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  f scratch alloca
139d0 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20  tions (N).)^.** 
139e0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
139f0 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69  nt must be a poi
13a00 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
13a10 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72  e aligned buffer
13a20 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
13a30 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
13a40 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
13a50 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f   will not use mo
13a60 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61  re than one scra
13a70 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20  tch buffers per 
13a80 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69  thread..** ^SQLi
13a90 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65  te will never re
13aa0 71 75 65 73 74 20 61 20 73 63 72 61 74 63 68 20  quest a scratch 
13ab0 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d  buffer that is m
13ac0 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69  ore than 6.** ti
13ad0 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  mes the database
13ae0 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e   page size..** ^
13af0 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20  If SQLite needs 
13b00 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c  needs additional
13b10 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
13b20 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ry beyond what i
13b30 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
13b40 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
13b50 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a   option, then .*
13b60 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
13b70 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65  c()] will be use
13b80 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
13b90 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70  memory needed.<p
13ba0 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61  >.** ^When the a
13bb0 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69  pplication provi
13bc0 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f  des any amount o
13bd0 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  f scratch memory
13be0 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45   using.** SQLITE
13bf0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c  _CONFIG_SCRATCH,
13c00 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75   SQLite avoids u
13c10 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67 65  nnecessary large
13c20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
13c30 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74  loc|heap allocat
13c40 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63  ions]..** This c
13c50 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20  an help [Robson 
13c60 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65  proof|prevent me
13c70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13c80 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f  failures] due to
13c90 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e   heap.** fragmen
13ca0 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65  tation in low-me
13cb0 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73 79  mory embedded sy
13cc0 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  stems..** </dd>.
13cd0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13ce0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
13cf0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13d00 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
13d10 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
13d20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
13d30 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73  GECACHE option s
13d40 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72  pecifies a memor
13d50 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53  y pool.** that S
13d60 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
13d70 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  r the database p
13d80 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74  age cache with t
13d90 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a  he default page.
13da0 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
13db0 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  ntation.  .** Th
13dc0 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
13dd0 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d   option is a no-
13de0 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  op if an applica
13df0 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65  tion-define page
13e00 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
13e10 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64  entation is load
13e20 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ed using the [SQ
13e30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13e40 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  HE2]..** ^There 
13e50 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
13e60 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
13e70 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20  NFIG_PAGECACHE: 
13e80 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  A pointer to.** 
13e90 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d  8-byte aligned m
13ea0 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68  emory (pMem), th
13eb0 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
13ec0 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28  age cache line (
13ed0 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20  sz),.** and the 
13ee0 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20  number of cache 
13ef0 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  lines (N)..** Th
13f00 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
13f10 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
13f20 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
13f30 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
13f40 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
13f50 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
13f60 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d   65536) plus som
13f70 65 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f  e extra bytes fo
13f80 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68  r each.** page h
13f90 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d  eader.  ^The num
13fa0 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74  ber of extra byt
13fb0 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65  es needed by the
13fc0 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20   page header.** 
13fd0 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
13fe0 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f  d using [SQLITE_
13ff0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
14000 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20  RSZ]..** ^It is 
14010 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20  harmless, apart 
14020 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20  from the wasted 
14030 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74  memory,.** for t
14040 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20  he sz parameter 
14050 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  to be larger tha
14060 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68  n necessary.  Th
14070 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65  e pMem.** argume
14080 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  nt must be eithe
14090 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
140a0 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   or a pointer to
140b0 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
140c0 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d  igned block of m
140d0 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73  emory of at leas
140e0 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74  t sz*N bytes, ot
140f0 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65  herwise.** subse
14100 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69  quent behavior i
14110 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
14120 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f  ^When pMem is no
14130 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77  t NULL, SQLite w
14140 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73  ill strive to us
14150 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
14160 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69  vided.** to sati
14170 73 66 79 20 70 61 67 65 20 63 61 63 68 65 20 6e  sfy page cache n
14180 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61  eeds, falling ba
14190 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  ck to [sqlite3_m
141a0 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61  alloc()] if.** a
141b0 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65   page cache line
141c0 20 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20   is larger than 
141d0 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20 61  sz bytes or if a
141e0 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62  ll of the pMem b
141f0 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61  uffer.** is exha
14200 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d  usted..** ^If pM
14210 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e  em is NULL and N
14220 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68   is non-zero, th
14230 65 6e 20 65 61 63 68 20 64 61 74 61 62 61 73 65  en each database
14240 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64   connection.** d
14250 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62  oes an initial b
14260 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ulk allocation f
14270 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  or page cache me
14280 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  mory.** from [sq
14290 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
142a0 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e  sufficient for N
142b0 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20   cache lines if 
142c0 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72  N is positive or
142d0 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62  .** of -1024*N b
142e0 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67  ytes if N is neg
142f0 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64  ative, . ^If add
14300 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
14310 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
14320 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
14330 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
14340 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a  y the initial.**
14350 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
14360 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  n SQLite goes to
14370 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14380 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66  ()] separately f
14390 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74  or each.** addit
143a0 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65  ional cache line
143b0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
143c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
143d0 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AP]] <dt>SQLITE_
143e0 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
143f0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
14400 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
14410 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
14420 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
14430 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61  y buffer .** tha
14440 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  t SQLite will us
14450 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
14460 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
14470 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
14480 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65  .** beyond those
14490 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79   provided for by
144a0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
144b0 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20  SCRATCH] and.** 
144c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
144d0 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54  AGECACHE]..** ^T
144e0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
144f0 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20  _HEAP option is 
14500 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
14510 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
14520 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74  iled.** with eit
14530 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  her [SQLITE_ENAB
14540 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b  LE_MEMSYS3] or [
14550 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
14560 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72  MSYS5] and retur
14570 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  ns.** [SQLITE_ER
14580 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20  ROR] if invoked 
14590 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54  otherwise..** ^T
145a0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
145b0 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49  rguments to SQLI
145c0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a  TE_CONFIG_HEAP:.
145d0 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69  ** An 8-byte ali
145e0 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20  gned pointer to 
145f0 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  the memory,.** t
14600 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
14610 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  es in the memory
14620 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65   buffer, and the
14630 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
14640 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  ion size..** ^If
14650 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   the first point
14660 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
14670 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c  ointer) is NULL,
14680 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76   then SQLite rev
14690 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67  erts.** to using
146a0 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d   its default mem
146b0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74  ory allocator (t
146c0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
146d0 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  () implementatio
146e0 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61  n),.** undoing a
146f0 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74  ny prior invocat
14700 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43  ion of [SQLITE_C
14710 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
14720 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72  ^If the.** memor
14730 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  y pointer is not
14740 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61   NULL then the a
14750 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
14760 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69  y.** allocator i
14770 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e  s engaged to han
14780 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74  dle all of SQLit
14790 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  es memory alloca
147a0 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54  tion needs..** T
147b0 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
147c0 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
147d0 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c  nter) must be al
147e0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
147f0 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f  te.** boundary o
14800 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
14810 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20  avior of SQLite 
14820 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
14830 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75  d..** The minimu
14840 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
14850 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32  e is capped at 2
14860 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65  **12. Reasonable
14870 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74   values.** for t
14880 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
14890 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32  ation size are 2
148a0 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38  **5 through 2**8
148b0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
148c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
148d0 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
148e0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
148f0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14900 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14910 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  TEX option takes
14920 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14930 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a  nt which is a.**
14940 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
14950 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
14960 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
14970 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
14980 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
14990 74 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65  t specifies alte
149a0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
149b0 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
149c0 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69   to be used.** i
149d0 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65  n place the mute
149e0 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
149f0 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
14a00 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
14a10 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
14a20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
14a30 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
14a40 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
14a50 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
14a60 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
14a70 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
14a80 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
14a90 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
14aa0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
14ab0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
14ac0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
14ad0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14ae0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
14af0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
14b00 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
14b10 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
14b20 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
14b30 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
14b40 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
14b50 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
14b60 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
14b70 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
14b80 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
14b90 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
14ba0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14bb0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
14bc0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
14bd0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
14be0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
14bf0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14c00 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20  GETMUTEX option 
14c10 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
14c20 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
14c30 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
14c40 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
14c50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
14c60 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
14c70 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
14c80 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
14c90 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
14ca0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
14cb0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
14cc0 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
14cd0 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
14ce0 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
14cf0 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
14d00 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  d the default mu
14d10 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  tex allocation.*
14d20 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
14d30 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74  a wrapper used t
14d40 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73  o track mutex us
14d50 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61  age for performa
14d60 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67  nce.** profiling
14d70 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72   or testing, for
14d80 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20   example.   ^If 
14d90 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
14da0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
14db0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14dc0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
14dd0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
14de0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
14df0 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
14e00 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
14e10 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
14e20 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
14e30 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
14e40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
14e50 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
14e60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14e70 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
14e80 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
14e90 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
14ea0 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
14eb0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14ec0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d  NFIG_LOOKASIDE]]
14ed0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14ee0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
14ef0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14f00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14f10 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74  OKASIDE option t
14f20 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
14f30 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
14f40 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  e.** the default
14f50 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69   size of lookasi
14f60 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63  de memory on eac
14f70 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  h [database conn
14f80 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20  ection]..** The 
14f90 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
14fa0 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
14fb0 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
14fc0 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
14fd0 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
14fe0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
14ff0 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
15000 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
15010 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
15020 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  (SQLITE_CONFIG_L
15030 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73  OOKASIDE.** sets
15040 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c   the <i>default<
15050 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69  /i> lookaside si
15060 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  ze. The [SQLITE_
15070 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
15080 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f  DE].** option to
15090 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
150a0 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73  fig()] can be us
150b0 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
150c0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f   lookaside.** co
150d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69  nfiguration on i
150e0 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63  ndividual connec
150f0 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  tions.)^ </dd>.*
15100 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15110 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c  NFIG_PCACHE2]] <
15120 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15130 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  _PCACHE2</dt>.**
15140 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
15150 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15160 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  2 option takes a
15170 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
15180 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20   which is .** a 
15190 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73  pointer to an [s
151a0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
151b0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
151c0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65   This object spe
151d0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e  cifies.** the in
151e0 74 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73  terface to a cus
151f0 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69  tom page cache i
15200 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e  mplementation.)^
15210 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  .** ^SQLite make
15220 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
15230 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
15240 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
15250 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
15260 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15270 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
15280 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15290 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
152a0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
152b0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
152c0 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  E2 option takes 
152d0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
152e0 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  t which.** is a 
152f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73  pointer to an [s
15300 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
15310 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
15320 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
15330 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74  f.** the current
15340 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
15350 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
15360 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
15370 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15380 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d  ITE_CONFIG_LOG]]
15390 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
153a0 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
153b0 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43  dd> The SQLITE_C
153c0 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
153d0 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66   is used to conf
153e0 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65  igure the SQLite
153f0 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f  .** global [erro
15400 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65  r log]..** (^The
15410 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
15420 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OG option takes 
15430 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61  two arguments: a
15440 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a   pointer to a.**
15450 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
15460 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20   call signature 
15470 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  of void(*)(void*
15480 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
15490 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69  ), .** and a poi
154a0 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49  nter to void. ^I
154b0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  f the function p
154c0 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
154d0 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76  LL, it is.** inv
154e0 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oked by [sqlite3
154f0 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65  _log()] to proce
15500 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20  ss each logging 
15510 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
15520 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  ** function poin
15530 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ter is NULL, the
15540 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
15550 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d   interface becom
15560 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e  es a no-op..** ^
15570 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72  The void pointer
15580 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63   that is the sec
15590 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
155a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
155b0 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  G is.** passed t
155c0 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
155d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
155e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
155f0 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
15600 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e  ** function when
15610 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69  ever that functi
15620 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
15630 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
15640 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
15650 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20  logger function 
15660 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
15670 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
15680 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   to the correspo
15690 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  nding.** [sqlite
156a0 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e  3_log()] call an
156b0 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  d is intended to
156c0 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f   be a [result co
156d0 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78  de] or an.** [ex
156e0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
156f0 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64  de].  ^The third
15700 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65   parameter passe
15710 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20  d to the logger 
15720 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67  is.** log messag
15730 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69  e after formatti
15740 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  ng via [sqlite3_
15750 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20  snprintf()]..** 
15760 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69  The SQLite loggi
15770 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ng interface is 
15780 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74  not reentrant; t
15790 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
157a0 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62  on.** supplied b
157b0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
157c0 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b  n must not invok
157d0 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
157e0 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20  erface..** In a 
157f0 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61  multi-threaded a
15800 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
15810 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
15820 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
15830 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74  nction must be t
15840 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e  hreadsafe. </dd>
15850 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15860 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74  CONFIG_URI]] <dt
15870 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  >SQLITE_CONFIG_U
15880 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20  RI.** <dd>^(The 
15890 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
158a0 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  I option takes a
158b0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
158c0 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a   of type int..**
158d0 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68   If non-zero, th
158e0 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  en URI handling 
158f0 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
15900 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61  led. If the para
15910 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a  meter is zero,.*
15920 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  * then URI handl
15930 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
15940 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20  disabled.)^ ^If 
15950 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
15960 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62  globally.** enab
15970 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d  led, all filenam
15980 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  es passed to [sq
15990 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
159a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
159b0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
159c0 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  open16()] or.** 
159d0 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72  specified as par
159e0 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f  t of [ATTACH] co
159f0 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72  mmands are inter
15a00 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20  preted as URIs, 
15a10 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66  regardless.** of
15a20 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
15a30 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
15a40 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65  _URI] flag is se
15a50 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  t when the datab
15a60 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
15a70 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66  n is opened. ^If
15a80 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20   it is globally 
15a90 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61  disabled, filena
15aa0 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20  mes are.** only 
15ab0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
15ac0 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54  RIs if the SQLIT
15ad0 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20  E_OPEN_URI flag 
15ae0 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a  is set when the.
15af0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
15b00 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
15b10 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20  . ^(By default, 
15b20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
15b30 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61  globally.** disa
15b40 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c  bled. The defaul
15b50 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63  t value may be c
15b60 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c  hanged by compil
15b70 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ing with the.** 
15b80 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
15b90 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
15ba0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
15bb0 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
15bc0 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c  G_INDEX_SCAN]] <
15bd0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15be0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
15bf0 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  SCAN.** <dd>^The
15c00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
15c10 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
15c20 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  AN option takes 
15c30 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72  a single integer
15c40 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69  .** argument whi
15c50 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  ch is interprete
15c60 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69  d as a boolean i
15c70 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c  n order to enabl
15c80 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20  e or disable.** 
15c90 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
15ca0 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
15cb0 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
15cc0 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70   in the query op
15cd0 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65  timizer..** ^The
15ce0 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
15cf0 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a   is determined.*
15d00 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  * by the [SQLITE
15d10 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f  _ALLOW_COVERING_
15d20 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70  INDEX_SCAN] comp
15d30 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
15d40 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69   or is "on".** i
15d50 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74  f that compile-t
15d60 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d  ime option is om
15d70 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62  itted..** The ab
15d80 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65  ility to disable
15d90 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
15da0 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
15db0 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
15dc0 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20  s.** is because 
15dd0 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79  some incorrectly
15de0 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70   coded legacy ap
15df0 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74  plications might
15e00 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20   malfunction.** 
15e10 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a  when the optimiz
15e20 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
15e30 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65  .  Providing the
15e40 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64   ability to.** d
15e50 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d  isable the optim
15e60 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74  ization allows t
15e70 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20  he older, buggy 
15e80 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
15e90 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68   to work.** with
15ea0 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20  out change even 
15eb0 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69  with newer versi
15ec0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
15ed0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15ee0 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b  NFIG_PCACHE]] [[
15ef0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15f00 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74  TPCACHE]].** <dt
15f10 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
15f20 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45  CACHE and SQLITE
15f30 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
15f40 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20  E.** <dd> These 
15f50 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f  options are obso
15f60 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20  lete and should 
15f70 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e  not be used by n
15f80 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79  ew code..** They
15f90 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f   are retained fo
15fa0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
15fb0 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72  atibility but ar
15fc0 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a  e now no-ops..**
15fd0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
15fe0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
15ff0 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  LOG]].** <dt>SQL
16000 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
16010 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  G.** <dd>This op
16020 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
16030 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65  ilable if sqlite
16040 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
16050 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
16060 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20  _ENABLE_SQLLOG] 
16070 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61  pre-processor ma
16080 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65  cro defined. The
16090 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
160a0 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70  should.** be a p
160b0 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63  ointer to a func
160c0 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69  tion of type voi
160d0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
160e0 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  e3*,const char*,
160f0 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65   int)..** The se
16100 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f  cond should be o
16110 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20  f type (void*). 
16120 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  The callback is 
16130 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c  invoked by the l
16140 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72  ibrary.** in thr
16150 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63  ee separate circ
16160 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74  umstances, ident
16170 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c  ified by the val
16180 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
16190 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d  .** fourth param
161a0 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75  eter. If the fou
161b0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
161c0 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74   0, then the dat
161d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
161e0 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  .** passed as th
161f0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
16200 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  t has just been 
16210 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72  opened. The thir
16220 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f  d argument.** po
16230 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72  ints to a buffer
16240 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
16250 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e  name of the main
16260 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20   database file. 
16270 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  If the.** fourth
16280 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c   parameter is 1,
16290 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   then the SQL st
162a0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65  atement that the
162b0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
162c0 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61  .** points to ha
162d0 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63  s just been exec
162e0 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65  uted. Or, if the
162f0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
16300 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20  r is 2, then.** 
16310 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  the connection b
16320 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74  eing passed as t
16330 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16340 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f  ter is being clo
16350 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72  sed. The.** thir
16360 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  d parameter is p
16370 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68  assed NULL In th
16380 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61  is case.  An exa
16390 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68  mple of using th
163a0 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  is.** configurat
163b0 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  ion option can b
163c0 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74  e seen in the "t
163d0 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f  est_sqllog.c" so
163e0 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20  urce file in.** 
163f0 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51  the canonical SQ
16400 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65  Lite source tree
16410 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
16420 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
16430 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  P_SIZE]].** <dt>
16440 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
16450 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e  AP_SIZE.** <dd>^
16460 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
16470 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77  AP_SIZE takes tw
16480 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  o 64-bit integer
16490 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29   (sqlite3_int64)
164a0 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
164b0 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20  are the default 
164c0 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20  mmap size limit 
164d0 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  (the default set
164e0 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41  ting for.** [PRA
164f0 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20  GMA mmap_size]) 
16500 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
16510 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
16520 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65  e limit..** ^The
16530 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
16540 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
16550 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62  en by each datab
16560 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75  ase connection u
16570 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74  sing.** either t
16580 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  he [PRAGMA mmap_
16590 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f  size] command, o
165a0 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a  r by using the.*
165b0 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
165c0 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
165d0 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20  control.  ^(The 
165e0 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
165f0 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c  mmap size.** wil
16600 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72  l be silently tr
16610 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73  uncated if neces
16620 73 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20  sary so that it 
16630 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20  does not exceed 
16640 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  the.** compile-t
16650 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70  ime maximum mmap
16660 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65   size set by the
16670 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f  .** [SQLITE_MAX_
16680 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69  MMAP_SIZE] compi
16690 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29  le-time option.)
166a0 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20  ^.** ^If either 
166b0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
166c0 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74   option is negat
166d0 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61  ive, then that a
166e0 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68  rgument is.** ch
166f0 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d  anged to its com
16700 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c  pile-time defaul
16710 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  t..**.** [[SQLIT
16720 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
16730 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74  EAPSIZE]].** <dt
16740 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  >SQLITE_CONFIG_W
16750 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a  IN32_HEAPSIZE.**
16760 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
16770 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
16780 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73  APSIZE option is
16790 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
167a0 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  if SQLite is.** 
167b0 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e  compiled for Win
167c0 64 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53  dows with the [S
167d0 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c  QLITE_WIN32_MALL
167e0 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OC] pre-processo
167f0 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e  r macro.** defin
16800 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  ed. ^SQLITE_CONF
16810 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
16820 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74  E takes a 32-bit
16830 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
16840 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20  r value.** that 
16850 73 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61  specifies the ma
16860 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68  ximum size of th
16870 65 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a  e created heap..
16880 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16890 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
168a0 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  SZ]].** <dt>SQLI
168b0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
168c0 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54  _HDRSZ.** <dd>^T
168d0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
168e0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70  _PCACHE_HDRSZ op
168f0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
16900 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
16910 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
16920 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
16930 72 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74  r and writes int
16940 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74  o that integer t
16950 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
16960 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20  ra.** bytes per 
16970 70 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f  page required fo
16980 72 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b  r each page in [
16990 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
169a0 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
169b0 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61   amount of extra
169c0 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20   space required 
169d0 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e  can change depen
169e0 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70  ding on the comp
169f0 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20  iler,.** target 
16a00 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51  platform, and SQ
16a10 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a  Lite version..**
16a20 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16a30 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c  FIG_PMASZ]].** <
16a40 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16a50 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54  _PMASZ.** <dd>^T
16a60 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16a70 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61  _PMASZ option ta
16a80 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
16a90 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
16aa0 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69  is an unsigned i
16ab0 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 20  nteger and sets 
16ac0 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41  the "Minimum PMA
16ad0 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d   Size" for the m
16ae0 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20  ultithreaded.** 
16af0 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 69  sorter to that i
16b00 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 66  nteger.  The def
16b10 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41  ault minimum PMA
16b20 20 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 20   Size is set by 
16b30 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  the.** [SQLITE_S
16b40 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d  ORTER_PMASZ] com
16b50 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
16b60 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 61  .  New threads a
16b70 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74  re launched.** t
16b80 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74  o help with sort
16b90 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e   operations when
16ba0 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 73   multithreaded s
16bb0 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61  orting.** is ena
16bc0 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 20  bled (using the 
16bd0 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d  [PRAGMA threads]
16be0 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68   command) and th
16bf0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74  e amount of cont
16c00 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72  ent.** to be sor
16c10 74 65 64 20 65 78 63 65 65 64 73 20 74 68 65 20  ted exceeds the 
16c20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20  page size times 
16c30 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74  the minimum of t
16c40 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61  he.** [PRAGMA ca
16c50 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e  che_size] settin
16c60 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65  g and this value
16c70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
16c80 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c  _CONFIG_STMTJRNL
16c90 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e  _SPILL]].** <dt>
16ca0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
16cb0 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20  MTJRNL_SPILL.** 
16cc0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
16cd0 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
16ce0 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b  SPILL option tak
16cf0 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
16d00 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 62  meter which.** b
16d10 65 63 6f 6d 65 73 20 74 68 65 20 5b 73 74 61 74  ecomes the [stat
16d20 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73  ement journal] s
16d30 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72  pill-to-disk thr
16d40 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74  eshold.  .** [St
16d50 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73  atement journals
16d60 5d 20 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65  ] are held in me
16d70 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68 65 69 72  mory until their
16d80 20 73 69 7a 65 20 28 69 6e 20 62 79 74 65 73 29   size (in bytes)
16d90 0a 2a 2a 20 65 78 63 65 65 64 73 20 74 68 69 73  .** exceeds this
16da0 20 74 68 72 65 73 68 6f 6c 64 2c 20 61 74 20 77   threshold, at w
16db0 68 69 63 68 20 70 6f 69 6e 74 20 74 68 65 79 20  hich point they 
16dc0 61 72 65 20 77 72 69 74 74 65 6e 20 74 6f 20 64  are written to d
16dd0 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68  isk..** Or if th
16de0 65 20 74 68 72 65 73 68 6f 6c 64 20 69 73 20 2d  e threshold is -
16df0 31 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  1, statement jou
16e00 72 6e 61 6c 73 20 61 72 65 20 61 6c 77 61 79 73  rnals are always
16e10 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69   held.** exclusi
16e20 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a  vely in memory..
16e30 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20 73 74  ** Since many st
16e40 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73  atement journals
16e50 20 6e 65 76 65 72 20 62 65 63 6f 6d 65 20 6c 61   never become la
16e60 72 67 65 2c 20 73 65 74 74 69 6e 67 20 74 68 65  rge, setting the
16e70 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68   spill.** thresh
16e80 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75 65 20 73  old to a value s
16e90 75 63 68 20 61 73 20 36 34 4b 69 42 20 63 61 6e  uch as 64KiB can
16ea0 20 67 72 65 61 74 6c 79 20 72 65 64 75 63 65 20   greatly reduce 
16eb0 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a  the amount of.**
16ec0 20 49 2f 4f 20 72 65 71 75 69 72 65 64 20 74 6f   I/O required to
16ed0 20 73 75 70 70 6f 72 74 20 73 74 61 74 65 6d 65   support stateme
16ee0 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  nt rollback..** 
16ef0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
16f00 65 20 66 6f 72 20 74 68 69 73 20 73 65 74 74 69  e for this setti
16f10 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  ng is controlled
16f20 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
16f30 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  TE_STMTJRNL_SPIL
16f40 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  L] compile-time 
16f50 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e  option..** </dl>
16f60 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
16f70 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
16f80 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69  THREAD  1  /* ni
16f90 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
16fa0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
16fb0 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e  THREAD   2  /* n
16fc0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
16fd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
16fe0 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20  ALIZED    3  /* 
16ff0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
17000 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
17010 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a  LOC        4  /*
17020 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
17030 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
17040 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
17050 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20  ETMALLOC     5  
17060 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
17070 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
17080 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17090 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36  _SCRATCH       6
170a0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
170b0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
170c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
170d0 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20  IG_PAGECACHE    
170e0 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   7  /* void*, in
170f0 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
17100 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17110 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20  NFIG_HEAP       
17120 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     8  /* void*, 
17130 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d  int nByte, int m
17140 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  in */.#define SQ
17150 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
17160 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20  TATUS     9  /* 
17170 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69  boolean */.#defi
17180 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17190 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30  _MUTEX        10
171a0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
171b0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  ex_methods* */.#
171c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
171d0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20  NFIG_GETMUTEX   
171e0 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33    11  /* sqlite3
171f0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
17200 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79  */./* previously
17210 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
17220 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69  HUNKALLOC 12 whi
17230 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64  ch is now unused
17240 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51  . */ .#define SQ
17250 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
17260 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20  ASIDE    13  /* 
17270 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
17280 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17290 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34  _PCACHE       14
172a0 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
172b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
172c0 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20  FIG_GETPCACHE   
172d0 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   15  /* no-op */
172e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
172f0 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20  CONFIG_LOG      
17300 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63      16  /* xFunc
17310 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
17320 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17330 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37  _URI          17
17340 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
17350 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17360 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31  G_PCACHE2      1
17370 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  8  /* sqlite3_pc
17380 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
17390 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
173a0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
173b0 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69  E2   19  /* sqli
173c0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
173d0 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
173e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
173f0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
17400 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a  N 20  /* int */.
17410 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17420 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20  ONFIG_SQLLOG    
17430 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f     21  /* xSqllo
17440 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  g, void* */.#def
17450 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17460 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32  G_MMAP_SIZE    2
17470 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e  2  /* sqlite3_in
17480 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  t64, sqlite3_int
17490 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  64 */.#define SQ
174a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
174b0 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20  2_HEAPSIZE      
174c0 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65  23  /* int nByte
174d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
174e0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
174f0 5f 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34  _HDRSZ        24
17500 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f    /* int *psz */
17510 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17520 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20  CONFIG_PMASZ    
17530 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f             25  /
17540 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73  * unsigned int s
17550 7a 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20  zPma */.#define 
17560 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
17570 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20  MTJRNL_SPILL    
17580 20 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79    26  /* int nBy
17590 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  te */../*.** CAP
175a0 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
175b0 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69  Connection Confi
175c0 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
175d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
175e0 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
175f0 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
17600 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
17610 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
17620 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
17630 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
17640 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
17650 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
17660 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
17670 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
17680 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
17690 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
176a0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
176b0 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
176c0 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
176d0 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
176e0 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
176f0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
17700 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
17710 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
17720 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  om [sqlite3_db_c
17730 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
17740 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
17750 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
17760 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62  ^The [sqlite3_db
17770 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
17780 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
17790 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
177a0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
177b0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
177c0 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
177d0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
177e0 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
177f0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
17800 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
17810 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
17820 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
17830 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72  option takes thr
17840 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  ee additional ar
17850 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
17860 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b  ermine the .** [
17870 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
17880 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66   allocator] conf
17890 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68  iguration for th
178a0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
178b0 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65  ection]..** ^The
178c0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
178d0 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  (the third param
178e0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
178f0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73  _db_config()] is
17900 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
17910 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72   a memory buffer
17920 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b   to use for look
17930 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  aside memory..**
17940 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
17950 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53  ment after the S
17960 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
17970 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a  OOKASIDE verb.**
17980 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20   may be NULL in 
17990 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74  which case SQLit
179a0 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20  e will allocate 
179b0 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65  the.** lookaside
179c0 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75   buffer itself u
179d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
179e0 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65  lloc()]. ^The se
179f0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
17a00 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
17a10 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
17a20 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68  uffer slot.  ^Th
17a30 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
17a40 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
17a50 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
17a60 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
17a70 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
17a80 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
17a90 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
17aa0 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
17ab0 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
17ac0 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
17ad0 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
17ae0 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
17af0 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
17b00 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
17b10 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f  y.  ^If the seco
17b20 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
17b30 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  * SQLITE_DBCONFI
17b40 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e  G_LOOKASIDE is n
17b50 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ot a multiple of
17b60 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e   8, it is intern
17b70 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20  ally.** rounded 
17b80 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74  down to the next
17b90 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c   smaller multipl
17ba0 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c  e of 8.  ^(The l
17bb0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a  ookaside memory.
17bc0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
17bd0 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20   for a database 
17be0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f  connection can o
17bf0 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77  nly be changed w
17c00 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e  hen that.** conn
17c10 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75  ection is not cu
17c20 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f  rrently using lo
17c30 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20  okaside memory, 
17c40 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  or in other word
17c50 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63  s.** when the "c
17c60 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65  urrent value" re
17c70 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
17c80 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d  lite3_db_status]
17c90 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  (D,[SQLITE_CONFI
17ca0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e  G_LOOKASIDE],...
17cb0 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e  ) is zero..** An
17cc0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61  y attempt to cha
17cd0 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
17ce0 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75  e memory configu
17cf0 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b  ration when look
17d00 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  aside.** memory 
17d10 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73  is in use leaves
17d20 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
17d30 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64  on unchanged and
17d40 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51   returns .** [SQ
17d50 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64  LITE_BUSY].)^</d
17d60 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
17d70 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
17d80 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a  BLE_FKEY</dt>.**
17d90 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
17da0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
17db0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
17dc0 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20  the enforcement 
17dd0 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  of.** [foreign k
17de0 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e  ey constraints].
17df0 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62    There should b
17e00 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
17e10 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
17e20 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17e30 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
17e40 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
17e50 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  sable FK enforce
17e60 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  ment,.** positiv
17e70 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65  e to enable FK e
17e80 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65  nforcement or ne
17e90 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
17ea0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a  FK enforcement.*
17eb0 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  * unchanged.  Th
17ec0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17ed0 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
17ee0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
17ef0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
17f00 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
17f10 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
17f20 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  r FK enforcement
17f30 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a   is off or on.**
17f40 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
17f50 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
17f60 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
17f70 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
17f80 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
17f90 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72  ase the FK enfor
17fa0 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69  cement setting i
17fb0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
17fc0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
17fd0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
17fe0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
17ff0 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GER</dt>.** <dd>
18000 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
18010 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
18020 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41  or disable [CREA
18030 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
18040 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65  ggers]..** There
18050 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
18060 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
18070 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
18080 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
18090 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
180a0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74  s 0 to disable t
180b0 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69  riggers,.** posi
180c0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74  tive to enable t
180d0 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74  riggers or negat
180e0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
180f0 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
18100 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
18110 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18120 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
18130 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
18140 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
18150 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
18160 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67  te whether trigg
18170 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ers are disabled
18180 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
18190 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
181a0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
181b0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
181c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
181d0 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
181e0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65  e the trigger se
181f0 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
18200 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
18210 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
18220 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18230 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45  LE_FTS3_TOKENIZE
18240 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
18250 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
18260 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
18270 20 64 69 73 61 62 6c 65 20 74 68 65 20 74 77 6f   disable the two
18280 2d 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72  -argument.** ver
18290 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74 73  sion of the [fts
182a0 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66  3_tokenizer()] f
182b0 75 6e 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73  unction which is
182c0 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
182d0 5b 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74  [FTS3] full-text
182e0 20 73 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65   search engine e
182f0 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65  xtension..** The
18300 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
18310 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
18320 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
18330 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
18340 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
18350 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
18360 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28   fts3_tokenizer(
18370 29 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ) or.** positive
18380 20 74 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f   to enable fts3_
18390 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e  tokenizer() or n
183a0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
183b0 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20   the setting.** 
183c0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
183d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
183e0 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
183f0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
18400 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
18410 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
18420 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
18430 72 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72  r fts3_tokenizer
18440 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20   is disabled or 
18450 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
18460 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
18470 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18480 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
18490 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
184a0 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
184b0 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73  e new setting is
184c0 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
184d0 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
184e0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
184f0 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f  FIG_ENABLE_LOAD_
18500 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a  EXTENSION</dt>.*
18510 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
18520 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
18530 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
18540 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
18550 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a  ad_extension()].
18560 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64  ** interface ind
18570 65 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68  ependently of th
18580 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e [load_extensio
18590 6e 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f  n()] SQL functio
185a0 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  n..** The [sqlit
185b0 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
185c0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20  xtension()] API 
185d0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
185e0 6c 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20  les both the.** 
185f0 43 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c  C-API [sqlite3_l
18600 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
18610 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e   and the SQL fun
18620 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65  ction [load_exte
18630 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65  nsion()]..** The
18640 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
18650 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
18660 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  ments..** When t
18670 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18680 74 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66  t to this interf
18690 61 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f  ace is 1, then o
186a0 6e 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69 73  nly the C-API is
186b0 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20  .** enabled and 
186c0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
186d0 20 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65   remains disable
186e0 64 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74  d.  If the first
186f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
18700 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
18710 73 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74  s 0, then both t
18720 68 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65  he C-API and the
18730 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72   SQL function ar
18740 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49  e disabled..** I
18750 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  f the first argu
18760 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e  ment is -1, then
18770 20 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20   no changes are 
18780 6d 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66  made to state of
18790 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43   either the.** C
187a0 2d 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20  -API or the SQL 
187b0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  function..** The
187c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
187d0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
187e0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
187f0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
18800 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
18810 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
18820 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
18830 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65  xtension()] inte
18840 72 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61  rface.** is disa
18850 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20  bled or enabled 
18860 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
18870 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
18880 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a   parameter may.*
18890 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * be a NULL poin
188a0 74 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ter, in which ca
188b0 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69  se the new setti
188c0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
188d0 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64  ed back..** </dd
188e0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
188f0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e  TE_DBCONFIG_MAIN
18900 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBNAME</dt>.** <
18910 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
18920 20 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e   is used to chan
18930 67 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ge the name of t
18940 68 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61  he "main" databa
18950 73 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e  se.** schema.  ^
18960 54 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e  The sole argumen
18970 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
18980 6f 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46  o a constant UTF
18990 38 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63  8 string.** whic
189a0 68 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  h will become th
189b0 65 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d  e new schema nam
189c0 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d  e in place of "m
189d0 61 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a  ain".  ^SQLite.*
189e0 2a 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20  * does not make 
189f0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65  a copy of the ne
18a00 77 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61  w main schema na
18a10 6d 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68  me string, so th
18a20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
18a30 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
18a40 74 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70  t the argument p
18a50 61 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20  assed into this 
18a60 44 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20  DBCONFIG option 
18a70 69 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20  is unchanged.** 
18a80 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 20  until after the 
18a90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18aa0 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c  ion closes..** <
18ab0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
18ac0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e  QLITE_DBCONFIG_N
18ad0 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c  O_CKPT_ON_CLOSE<
18ae0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75  /dt>.** <dd> Usu
18af0 61 6c 6c 79 2c 20 77 68 65 6e 20 61 20 64 61 74  ally, when a dat
18b00 61 62 61 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64  abase in wal mod
18b10 65 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 64  e is closed or d
18b20 65 74 61 63 68 65 64 20 66 72 6f 6d 20 61 20 0a  etached from a .
18b30 2a 2a 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  ** database hand
18b40 6c 65 2c 20 53 51 4c 69 74 65 20 63 68 65 63 6b  le, SQLite check
18b50 73 20 69 66 20 74 68 69 73 20 77 69 6c 6c 20 6d  s if this will m
18b60 65 61 6e 20 74 68 61 74 20 74 68 65 72 65 20 61  ean that there a
18b70 72 65 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f  re now no .** co
18b80 6e 6e 65 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c  nnections at all
18b90 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
18ba0 2e 20 49 66 20 73 6f 2c 20 69 74 20 70 65 72 66  . If so, it perf
18bb0 6f 72 6d 73 20 61 20 63 68 65 63 6b 70 6f 69 6e  orms a checkpoin
18bc0 74 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  t .** operation 
18bd0 62 65 66 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74  before closing t
18be0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54  he connection. T
18bf0 68 69 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62  his option may b
18c00 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65  e used to.** ove
18c10 72 72 69 64 65 20 74 68 69 73 20 62 65 68 61 76  rride this behav
18c20 69 6f 75 72 2e 20 54 68 65 20 66 69 72 73 74 20  iour. The first 
18c30 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
18c40 20 74 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69   to this operati
18c50 6f 6e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65  on.** is an inte
18c60 67 65 72 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74  ger - non-zero t
18c70 6f 20 64 69 73 61 62 6c 65 20 63 68 65 63 6b 70  o disable checkp
18c80 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20  oints-on-close, 
18c90 6f 72 20 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20  or zero (the.** 
18ca0 64 65 66 61 75 6c 74 29 20 74 6f 20 65 6e 61 62  default) to enab
18cb0 6c 65 20 74 68 65 6d 2e 20 54 68 65 20 73 65 63  le them. The sec
18cc0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
18cd0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
18ce0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f   integer.** into
18cf0 20 77 68 69 63 68 20 69 73 20 77 72 69 74 74 65   which is writte
18d00 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
18d10 63 61 74 65 20 77 68 65 74 68 65 72 20 63 68 65  cate whether che
18d20 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73  ckpoints-on-clos
18d30 65 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 64  e.** have been d
18d40 69 73 61 62 6c 65 64 20 2d 20 30 20 69 66 20 74  isabled - 0 if t
18d50 68 65 79 20 61 72 65 20 6e 6f 74 20 64 69 73 61  hey are not disa
18d60 62 6c 65 64 2c 20 31 20 69 66 20 74 68 65 79 20  bled, 1 if they 
18d70 61 72 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  are..** </dd>.**
18d80 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
18d90 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
18da0 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 20  NFIG_MAINDBNAME 
18db0 20 20 20 20 20 20 20 20 20 20 20 31 30 30 30 20             1000 
18dc0 2f 2a 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 2a  /* const char* *
18dd0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18de0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
18df0 49 44 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IDE             
18e00 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e  1001 /* void* in
18e10 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
18e20 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18e30 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20  _ENABLE_FKEY    
18e40 20 20 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69         1002 /* i
18e50 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
18e60 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18e70 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
18e80 52 20 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a  R        1003 /*
18e90 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
18ea0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
18eb0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33  NFIG_ENABLE_FTS3
18ec0 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20  _TOKENIZER 1004 
18ed0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
18ee0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
18ef0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f  CONFIG_ENABLE_LO
18f00 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30  AD_EXTENSION 100
18f10 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  5 /* int int* */
18f20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18f30 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54  DBCONFIG_NO_CKPT
18f40 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20 20 20 20 31  _ON_CLOSE      1
18f50 30 30 36 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  006 /* int int* 
18f60 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  */.../*.** CAPI3
18f70 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
18f80 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20  isable Extended 
18f90 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
18fa0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
18fb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
18fc0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
18fd0 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
18fe0 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
18ff0 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
19000 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
19010 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
19020 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
19030 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
19040 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
19050 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
19060 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
19070 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
19080 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
19090 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
190a0 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
190b0 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
190c0 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
190d0 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45  sert Rowid.** ME
190e0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
190f0 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
19100 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74  in most SQLite t
19110 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f  ables (except fo
19120 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  r [WITHOUT ROWID
19130 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73  ] tables).** has
19140 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
19150 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
19160 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
19170 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69  e [ROWID | "rowi
19180 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20  d"]. ^The rowid 
19190 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
191a0 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
191b0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
191c0 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
191d0 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
191e0 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
191f0 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
19200 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
19210 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
19220 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74  olumns. ^If.** t
19230 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
19240 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49  olumn of type [I
19250 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
19260 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f  EY] then that co
19270 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68  lumn.** is anoth
19280 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  er alias for the
19290 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   rowid..**.** ^T
192a0 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  he sqlite3_last_
192b0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
192c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
192d0 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
192e0 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65   the .** most re
192f0 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
19300 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20  [INSERT] into a 
19310 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b  rowid table or [
19320 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
19330 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f  * on database co
19340 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e  nnection D..** ^
19350 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49  Inserts into [WI
19360 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
19370 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f  les are not reco
19380 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20  rded..** ^If no 
19390 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
193a0 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20  RT]s into rowid 
193b0 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65  tables.** have e
193c0 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
193d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
193e0 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74  nection D, .** t
193f0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  hen sqlite3_last
19400 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
19410 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
19420 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
19430 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
19440 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72  hin a trigger or
19450 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75   within a [virtu
19460 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74  al table].** met
19470 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72  hod, then this r
19480 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75  outine will retu
19490 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  rn the [rowid] o
194a0 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a  f the inserted.*
194b0 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73  * row as long as
194c0 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
194d0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
194e0 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e  thod is running.
194f0 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
19500 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
19510 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
19520 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65   ends, the value
19530 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79   returned .** by
19540 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
19550 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74  verts to what it
19560 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20   was before the 
19570 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
19580 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68  al.** table meth
19590 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a  od began.)^.**.*
195a0 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
195b0 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
195c0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
195d0 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
195e0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
195f0 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
19600 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
19610 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
19620 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
19630 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
19640 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
19650 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
19660 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
19670 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
19680 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
19690 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
196a0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
196b0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
196c0 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
196d0 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
196e0 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
196f0 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
19700 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
19710 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
19720 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
19730 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
19740 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
19750 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
19760 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
19770 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
19780 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
19790 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
197a0 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
197b0 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
197c0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
197d0 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
197e0 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
197f0 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
19800 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
19810 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
19820 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
19830 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
19840 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
19850 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
19860 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
19870 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
19880 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
19890 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
198a0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
198b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
198c0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
198d0 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
198e0 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
198f0 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
19900 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
19910 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
19920 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
19930 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
19940 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
19950 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
19960 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
19970 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
19980 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
19990 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
199a0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
199b0 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
199c0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
199d0 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
199e0 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
199f0 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
19a00 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
19a10 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
19a20 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
19a30 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
19a40 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
19a50 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
19a60 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
19a70 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
19a80 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
19a90 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
19aa0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
19ab0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
19ac0 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72   modified, inser
19ad0 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65  ted or.** delete
19ae0 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
19af0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
19b00 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
19b10 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
19b20 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61  tement on the da
19b30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19b40 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  n specified by t
19b50 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
19b60 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67  r..** ^Executing
19b70 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
19b80 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
19b90 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79   does not modify
19ba0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
19bb0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
19bc0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
19bd0 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
19be0 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68  e directly by th
19bf0 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  e INSERT, UPDATE
19c00 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
19c10 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  ment are.** cons
19c20 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61  idered - auxilia
19c30 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
19c40 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49  d by [CREATE TRI
19c50 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
19c60 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  , .** [foreign k
19c70 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b  ey actions] or [
19c80 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
19c90 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
19ca0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
19cb0 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74  ** .** Changes t
19cc0 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
19cd0 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79  e intercepted by
19ce0 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46   .** [INSTEAD OF
19cf0 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45   trigger | INSTE
19d00 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20  AD OF triggers] 
19d10 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
19d20 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20   ^The value .** 
19d30 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
19d40 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d  te3_changes() im
19d50 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20  mediately after 
19d60 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
19d70 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20  E or .** DELETE 
19d80 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e  statement run on
19d90 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79   a view is alway
19da0 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61  s zero. Only cha
19db0 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61  nges made to rea
19dc0 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65  l .** tables are
19dd0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
19de0 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20  Things are more 
19df0 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74  complicated if t
19e00 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
19e10 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
19e20 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69  .** executed whi
19e30 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  le a trigger pro
19e40 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gram is running.
19e50 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e   This may happen
19e60 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72   if the.** progr
19e70 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61  am uses the [cha
19e80 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
19e90 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65  ion], or if some
19ea0 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a   other callback.
19eb0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f  ** function invo
19ec0 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  kes sqlite3_chan
19ed0 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ges() directly. 
19ee0 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20  Essentially:.** 
19ef0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
19f00 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65  i> ^(Before ente
19f10 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70  ring a trigger p
19f20 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65  rogram the value
19f30 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
19f40 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63         sqlite3_c
19f50 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
19f60 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65  n is saved. Afte
19f70 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72  r the trigger pr
19f80 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20  ogram .**       
19f90 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74   has finished, t
19fa0 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75  he original valu
19fb0 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e  e is restored.)^
19fc0 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  .** .**   <li> ^
19fd0 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65  (Within a trigge
19fe0 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49  r program each I
19ff0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e  NSERT, UPDATE an
1a000 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20  d DELETE .**    
1a010 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65      statement se
1a020 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ts the value ret
1a030 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1a040 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
1a050 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c        upon compl
1a060 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e  etion as normal.
1a070 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73   Of course, this
1a080 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20   value will not 
1a090 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20  include .**     
1a0a0 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70     any changes p
1a0b0 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d  erformed by sub-
1a0c0 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65  triggers, as the
1a0d0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1a0e0 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61  () .**        va
1a0f0 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65  lue will be save
1a100 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61  d and restored a
1a110 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72  fter each sub-tr
1a120 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e  igger has run.)^
1a130 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a  .** </ul>.** .**
1a140 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61   ^This means tha
1a150 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73  t if the changes
1a160 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  () SQL function 
1a170 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20  (or similar) is 
1a180 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66  used.** by the f
1a190 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44  irst INSERT, UPD
1a1a0 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
1a1b0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
1a1c0 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a   trigger, it .**
1a1d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
1a1e0 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74  ue as set when t
1a1f0 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65  he calling state
1a200 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75  ment began execu
1a210 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20  ting..** ^If it 
1a220 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73  is used by the s
1a230 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75  econd or subsequ
1a240 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65  ent such stateme
1a250 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
1a260 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c  ger .** program,
1a270 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1a280 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65  ned reflects the
1a290 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1a2a0 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20  modified by the 
1a2b0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53  .** previous INS
1a2c0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1a2d0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1a2e0 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
1a2f0 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53  trigger..**.** S
1a300 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
1a310 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1a320 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
1a330 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
1a340 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
1a350 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
1a360 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1a370 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1a380 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
1a390 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
1a3a0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
1a3b0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
1a3c0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
1a3d0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
1a3e0 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
1a3f0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
1a400 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1a410 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
1a420 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
1a430 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
1a440 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
1a450 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
1a460 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
1a470 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ied.** METHOD: s
1a480 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1a490 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
1a4a0 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  rns the total nu
1a4b0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73  mber of rows ins
1a4c0 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20  erted, modified 
1a4d0 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
1a4e0 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   all [INSERT], [
1a4f0 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
1a500 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63  TE] statements c
1a510 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63  ompleted.** sinc
1a520 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
1a530 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70  onnection was op
1a540 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ened, including 
1a550 74 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61  those executed a
1a560 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69  s.** part of tri
1a570 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e  gger programs. ^
1a580 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
1a590 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
1a5a0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65  statement.** doe
1a5b0 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65  s not affect the
1a5c0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a5d0 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
1a5e0 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a  _changes()..** .
1a5f0 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65  ** ^Changes made
1a600 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72   as part of [for
1a610 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
1a620 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69  ] are included i
1a630 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20  n the.** count, 
1a640 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61  but those made a
1a650 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43  s part of REPLAC
1a660 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  E constraint res
1a670 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e  olution are.** n
1a680 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  ot. ^Changes to 
1a690 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
1a6a0 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49  intercepted by I
1a6b0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1a6c0 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  rs .** are not c
1a6d0 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53  ounted..** .** S
1a6e0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
1a6f0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
1a700 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
1a710 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
1a720 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
1a730 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e [total_changes
1a740 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1a750 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1a760 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
1a770 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
1a780 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
1a790 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
1a7a0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
1a7b0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
1a7c0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
1a7d0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
1a7e0 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
1a7f0 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
1a800 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
1a810 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1a820 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
1a830 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a840 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
1a850 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
1a860 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1a870 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1a880 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
1a890 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
1a8a0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
1a8b0 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
1a8c0 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
1a8d0 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
1a8e0 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
1a8f0 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
1a900 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
1a910 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
1a920 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
1a930 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
1a940 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
1a950 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
1a960 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
1a970 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
1a980 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
1a990 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
1a9a0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
1a9b0 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
1a9c0 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
1a9d0 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
1a9e0 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
1a9f0 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
1aa00 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
1aa10 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
1aa20 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
1aa30 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
1aa40 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
1aa50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
1aa60 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
1aa70 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
1aa80 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
1aa90 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
1aaa0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
1aab0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
1aac0 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
1aad0 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
1aae0 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
1aaf0 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
1ab00 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
1ab10 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
1ab20 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
1ab30 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
1ab40 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
1ab50 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
1ab60 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
1ab70 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
1ab80 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
1ab90 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
1aba0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
1abb0 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
1abc0 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
1abd0 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
1abe0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
1abf0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
1ac00 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
1ac10 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
1ac20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
1ac30 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
1ac40 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
1ac50 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
1ac60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1ac70 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
1ac80 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
1ac90 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
1aca0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
1acb0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1acc0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
1acd0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
1ace0 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
1acf0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1ad00 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1ad10 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
1ad20 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1ad30 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
1ad40 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
1ad50 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
1ad60 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
1ad70 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
1ad80 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
1ad90 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
1ada0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
1adb0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
1adc0 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
1add0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1ade0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1adf0 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
1ae00 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
1ae10 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
1ae20 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
1ae30 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1ae40 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
1ae50 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
1ae60 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
1ae70 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
1ae80 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
1ae90 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1aea0 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
1aeb0 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
1aec0 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
1aed0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1aee0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1aef0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1af00 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
1af10 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
1af20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1af30 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
1af40 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
1af50 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
1af60 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
1af70 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
1af80 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20  happen..*/.void 
1af90 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1afa0 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
1afb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
1afc0 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
1afd0 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
1afe0 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
1aff0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1b000 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63   useful during c
1b010 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
1b020 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
1b030 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
1b040 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
1b050 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20  seems to form a 
1b060 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
1b070 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
1b080 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
1b090 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
1b0a0 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
1b0b0 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
1b0c0 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
1b0d0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1b0e0 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20  return 1 if the 
1b0f0 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
1b100 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
1b110 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
1b120 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74  tement.  ^A stat
1b130 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
1b140 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
1b150 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
1b160 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
1b170 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
1b180 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
1b190 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
1b1a0 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
1b1b0 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f  ment.  ^Semicolo
1b1c0 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
1b1d0 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
1b1e0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
1b1f0 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
1b200 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
1b210 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
1b220 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
1b230 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
1b240 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
1b250 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
1b260 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
1b270 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
1b280 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
1b290 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ent terminator. 
1b2a0 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20   ^Whitespace.** 
1b2b0 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61  and comments tha
1b2c0 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e  t follow the fin
1b2d0 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65  al semicolon are
1b2e0 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
1b2f0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1b300 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
1b310 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
1b320 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a  omplete.  ^If a.
1b330 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
1b340 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e  tion fails, then
1b350 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73   SQLITE_NOMEM is
1b360 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1b370 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1b380 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
1b390 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
1b3a0 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
1b3b0 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
1b3c0 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
1b3d0 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66   SQL..**.** ^(If
1b3e0 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20   SQLite has not 
1b3f0 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  been initialized
1b400 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1b410 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72  initialize()] pr
1b420 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b  ior .** to invok
1b430 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ing sqlite3_comp
1b440 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71  lete16() then sq
1b450 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
1b460 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
1b470 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
1b480 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  y sqlite3_comple
1b490 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74  te16().  If that
1b4a0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
1b4b0 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  fails,.** then t
1b4c0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1b4d0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d  from sqlite3_com
1b4e0 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62  plete16() will b
1b4f0 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65  e non-zero.** re
1b500 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1b510 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69  her or not the i
1b520 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70  nput SQL is comp
1b530 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  lete.)^.**.** Th
1b540 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
1b550 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
1b560 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
1b570 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1b580 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
1b590 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
1b5a0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1b5b0 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
1b5c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1b5d0 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
1b5e0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
1b5f0 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
1b600 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
1b610 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
1b620 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
1b630 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
1b640 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
1b650 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
1b660 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
1b670 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
1b680 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45  USY Errors.** KE
1b690 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61  YWORDS: {busy-ha
1b6a0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20  ndler callback} 
1b6b0 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a  {busy handler}.*
1b6c0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1b6d0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
1b6e0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1b6f0 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65  r(D,X,P) routine
1b700 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
1b710 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74   function X.** t
1b720 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
1b730 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  oked with argume
1b740 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  nt P whenever.**
1b750 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
1b760 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20  ade to access a 
1b770 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61  database table a
1b780 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
1b790 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1b7a0 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61  ection] D when a
1b7b0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
1b7c0 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
1b7d0 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64  the table locked
1b7e0 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
1b7f0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20  _busy_handler() 
1b800 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
1b810 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a  d to implement.*
1b820 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  * [sqlite3_busy_
1b830 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b  timeout()] and [
1b840 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1b850 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  out]..**.** ^If 
1b860 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
1b870 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
1b880 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1b890 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
1b8a0 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
1b8b0 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
1b8c0 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75  ock.  ^If the bu
1b8d0 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
1b8e0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
1b8f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69   the callback mi
1b900 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
1b910 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
1b920 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  s..**.** ^The fi
1b930 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1b940 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1b950 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
1b960 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
1b970 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
1b980 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
1b990 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
1b9a0 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20  andler().  ^The 
1b9b0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
1b9c0 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  to.** the busy h
1b9d0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
1b9e0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
1b9f0 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
1ba00 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
1ba10 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
1ba20 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20   previously for 
1ba30 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67  the same locking
1ba40 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
1ba50 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
1ba60 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
1ba70 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
1ba80 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
1ba90 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
1baa0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
1bab0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73  [SQLITE_BUSY] is
1bac0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20   returned.** to 
1bad0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
1bae0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
1baf0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
1bb00 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
1bb10 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
1bb20 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
1bb30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
1bb40 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
1bb50 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
1bb60 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
1bb70 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
1bb80 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
1bb90 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
1bba0 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
1bbb0 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
1bbc0 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
1bbd0 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
1bbe0 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
1bbf0 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
1bc00 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
1bc10 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
1bc20 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
1bc30 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
1bc40 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61  USY].** to the a
1bc50 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65  pplication inste
1bc60 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
1bc70 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  he .** busy hand
1bc80 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
1bc90 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
1bca0 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
1bcb0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
1bcc0 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
1bcd0 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
1bce0 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
1bcf0 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
1bd00 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1bd10 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
1bd20 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
1bd30 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
1bd40 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
1bd50 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
1bd60 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
1bd70 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
1bd80 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
1bd90 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
1bda0 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
1bdb0 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
1bdc0 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
1bdd0 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
1bde0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
1bdf0 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
1be00 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
1be10 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
1be20 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
1be30 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
1be40 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
1be50 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
1be60 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
1be70 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
1be80 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
1be90 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
1bea0 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
1beb0 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
1bec0 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
1bed0 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
1bee0 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
1bef0 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
1bf00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
1bf10 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
1bf20 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
1bf30 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
1bf40 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
1bf50 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
1bf60 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
1bf70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1bf80 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
1bf90 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
1bfa0 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
1bfb0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
1bfc0 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
1bfd0 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
1bfe0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1bff0 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61  out()].** or eva
1c000 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20  luating [PRAGMA 
1c010 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20  busy_timeout=N] 
1c020 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a  will change the.
1c030 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ** busy handler 
1c040 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61  and thus clear a
1c050 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ny previously se
1c060 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  t busy handler..
1c070 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
1c080 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
1c090 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
1c0a0 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
1c0b0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1c0c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1c0d0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
1c0e0 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f  y handler.  In o
1c0f0 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74  ther words,.** t
1c100 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1c110 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
1c120 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
1c130 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
1c140 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
1c150 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
1c160 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
1c170 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
1c180 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c190 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
1c1a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1c1b0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1c1c0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
1c1d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
1c1e0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
1c1f0 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  ,int(*)(void*,in
1c200 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  t),void*);../*.*
1c210 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
1c220 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a  A Busy Timeout.*
1c230 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1c240 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  3.**.** ^This ro
1c250 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
1c260 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1c270 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
1c280 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
1c290 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
1c2a0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
1c2b0 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
1c2c0 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
1c2d0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
1c2e0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
1c2f0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
1c300 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1c310 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1c320 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
1c330 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
1c340 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1c350 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1c360 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
1c370 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
1c380 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
1c390 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
1c3a0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
1c3b0 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  E_BUSY]..**.** ^
1c3c0 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
1c3d0 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
1c3e0 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
1c3f0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
1c400 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
1c410 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
1c420 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
1c430 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
1c440 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
1c450 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
1c460 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1c470 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e  onnection] at an
1c480 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
1c490 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
1c4a0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
1c4b0 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
1c4c0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1c4d0 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
1c4e0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
1c4f0 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
1c500 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
1c510 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
1c520 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
1c530 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  :  [PRAGMA busy_
1c540 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20  timeout].*/.int 
1c550 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1c560 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
1c570 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
1c580 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
1c590 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
1c5a0 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
1c5b0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
1c5c0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ite3.**.** This 
1c5d0 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
1c5e0 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
1c5f0 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
1c600 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1c610 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
1c620 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
1c630 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
1c640 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
1c650 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
1c660 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
1c670 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
1c680 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
1c690 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
1c6a0 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
1c6b0 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
1c6c0 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
1c6d0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
1c6e0 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
1c6f0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
1c700 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
1c710 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
1c720 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
1c730 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
1c740 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
1c750 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
1c760 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
1c770 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
1c780 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
1c790 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
1c7a0 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
1c7b0 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
1c7c0 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
1c7d0 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
1c7e0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
1c7f0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1c800 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
1c810 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
1c820 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1c830 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
1c840 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
1c850 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
1c860 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
1c870 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
1c880 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
1c890 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1c8a0 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
1c8b0 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
1c8c0 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
1c8d0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
1c8e0 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
1c8f0 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
1c900 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
1c910 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
1c920 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
1c930 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
1c940 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
1c950 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1c960 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
1c970 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
1c980 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1c990 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
1c9a0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1c9b0 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
1c9c0 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
1c9d0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
1c9e0 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
1c9f0 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
1ca00 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
1ca10 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
1ca20 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
1ca30 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
1ca40 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
1ca50 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
1ca60 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1ca70 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
1ca80 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
1ca90 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
1caa0 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
1cab0 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
1cac0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1cad0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1cae0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1caf0 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
1cb00 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
1cb10 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1cb20 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
1cb30 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
1cb40 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
1cb50 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
1cb60 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
1cb70 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
1cb80 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1cb90 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
1cba0 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
1cbb0 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
1cbc0 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
1cbd0 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
1cbe0 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
1cbf0 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
1cc00 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
1cc10 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
1cc20 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
1cc30 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
1cc40 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
1cc50 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
1cc60 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1cc70 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1cc80 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
1cc90 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1cca0 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
1ccb0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1ccc0 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
1ccd0 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
1cce0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
1ccf0 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
1cd00 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1cd10 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
1cd20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1cd30 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
1cd40 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1cd50 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
1cd60 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
1cd70 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
1cd80 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
1cd90 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
1cda0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1cdb0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
1cdc0 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
1cdd0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
1cde0 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
1cdf0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1ce00 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
1ce10 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
1ce20 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
1ce30 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
1ce40 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
1ce50 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
1ce60 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
1ce70 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
1ce80 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
1ce90 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
1cea0 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
1ceb0 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
1cec0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
1ced0 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
1cee0 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
1cef0 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
1cf00 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
1cf10 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
1cf20 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
1cf30 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
1cf40 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
1cf50 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
1cf60 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
1cf70 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
1cf80 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
1cf90 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1cfa0 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
1cfb0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
1cfc0 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
1cfd0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1cfe0 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
1cff0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1d000 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
1d010 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
1d020 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
1d030 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
1d040 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1d050 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
1d060 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
1d070 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
1d080 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
1d090 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
1d0a0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1d0b0 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
1d0c0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
1d0d0 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
1d0e0 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
1d0f0 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
1d100 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
1d110 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
1d120 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
1d130 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
1d140 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
1d150 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
1d160 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
1d170 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
1d180 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
1d190 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
1d1a0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
1d1b0 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
1d1c0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
1d1d0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1d1e0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1d1f0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e  errmsg()]..*/.in
1d200 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
1d210 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
1d220 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
1d230 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
1d240 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1d250 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
1d260 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
1d270 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
1d280 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
1d290 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
1d2a0 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
1d2b0 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
1d2c0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1d2d0 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
1d2e0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
1d2f0 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
1d300 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1d310 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
1d320 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1d330 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
1d340 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
1d350 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
1d360 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
1d370 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
1d380 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
1d390 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
1d3a0 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
1d3b0 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
1d3c0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1d3d0 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
1d3e0 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
1d3f0 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
1d400 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
1d410 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
1d420 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
1d430 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1d440 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20  understand most 
1d450 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26  of the common K&
1d460 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  R formatting opt
1d470 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f  ions,.** plus so
1d480 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f  me additional no
1d490 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61  n-standard forma
1d4a0 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65 6c  ts, detailed bel
1d4b0 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ow..** Note that
1d4c0 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72   some of the mor
1d4d0 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 74  e obscure format
1d4e0 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f  ting options fro
1d4f0 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69  m recent.** C-li
1d500 62 72 61 72 79 20 73 74 61 6e 64 61 72 64 73 20  brary standards 
1d510 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d  are omitted from
1d520 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61   this implementa
1d530 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
1d540 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1d550 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
1d560 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
1d570 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
1d580 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
1d590 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
1d5a0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
1d5b0 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
1d5c0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
1d5d0 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
1d5e0 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
1d5f0 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
1d600 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1d610 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
1d620 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
1d630 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
1d640 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1d650 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
1d660 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
1d670 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1d680 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
1d690 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ing..**.** ^(The
1d6a0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1d6b0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
1d6c0 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
1d6d0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
1d6e0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1d6f0 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
1d700 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
1d710 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
1d720 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
1d730 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1d740 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
1d750 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
1d760 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
1d770 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
1d780 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
1d790 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
1d7a0 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
1d7b0 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
1d7c0 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
1d7d0 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
1d7e0 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
1d7f0 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
1d800 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
1d810 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1d820 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
1d830 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
1d840 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1d850 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1d860 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
1d870 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
1d880 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
1d890 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
1d8a0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1d8b0 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
1d8c0 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
1d8d0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1d8e0 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
1d8f0 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
1d900 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
1d910 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
1d920 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
1d930 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1d940 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1d950 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
1d960 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
1d970 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
1d980 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
1d990 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
1d9a0 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
1d9b0 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
1d9c0 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
1d9d0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
1d9e0 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
1d9f0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
1da00 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
1da10 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
1da20 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
1da30 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
1da40 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
1da50 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
1da60 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
1da70 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
1da80 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
1da90 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
1daa0 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
1dab0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
1dac0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  The sqlite3_vsnp
1dad0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1dae0 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72  is a varargs ver
1daf0 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  sion of sqlite3_
1db00 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a  snprintf()..**.*
1db10 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1db20 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
1db30 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
1db40 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
1db50 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
1db60 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
1db70 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
1db80 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
1db90 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
1dba0 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
1dbb0 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
1dbc0 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
1dbd0 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
1dbe0 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64 20   "%Q", "%w" and 
1dbf0 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
1dc00 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74  .** ^(The %q opt
1dc10 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1dc20 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62  s in that it sub
1dc30 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74  stitutes a nul-t
1dc40 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1dc50 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
1dc60 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
1dc70 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
1dc80 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
1dc90 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
1dca0 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
1dcb0 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
1dcc0 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20   literal.)^  By 
1dcd0 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
1dce0 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
1dcf0 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
1dd00 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
1dd10 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
1dd20 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
1dd30 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
1dd40 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
1dd50 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
1dd60 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
1dd70 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
1dd80 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1dd90 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1dda0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
1ddb0 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
1ddc0 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
1ddd0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1dde0 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
1ddf0 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
1de00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1de10 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1de20 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1de30 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1de40 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1de50 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1de60 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
1de70 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
1de80 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1de90 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1dea0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1deb0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1dec0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1ded0 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
1dee0 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
1def0 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
1df00 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
1df10 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
1df20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
1df30 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
1df40 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1df50 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1df60 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1df70 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1df80 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
1df90 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
1dfa0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1dfb0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
1dfc0 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
1dfd0 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
1dfe0 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
1dff0 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
1e000 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
1e010 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
1e020 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1e030 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1e040 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1e050 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1e060 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
1e070 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1e080 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
1e090 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
1e0a0 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
1e0b0 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
1e0c0 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
1e0d0 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
1e0e0 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
1e0f0 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
1e100 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
1e110 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ral..**.** ^(The
1e120 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
1e130 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
1e140 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
1e150 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
1e160 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
1e170 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
1e180 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
1e190 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
1e1a0 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
1e1b0 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
1e1c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
1e1d0 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
1e1e0 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
1e1f0 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
1e200 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53  le quotes).)^  S
1e210 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
1e220 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
1e230 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1e240 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1e250 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1e260 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1e270 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1e280 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
1e290 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1e2a0 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1e2b0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1e2c0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1e2d0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1e2e0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
1e2f0 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
1e300 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
1e310 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1e320 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
1e330 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
1e340 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
1e350 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1e360 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  r..**.** ^(The "
1e370 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %w" formatting o
1e380 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25  ption is like "%
1e390 71 22 20 65 78 63 65 70 74 20 74 68 61 74 20 69  q" except that i
1e3a0 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20  t expects to.** 
1e3b0 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74  be contained wit
1e3c0 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65  hin double-quote
1e3d0 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69 6e  s instead of sin
1e3e0 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 20  gle quotes, and 
1e3f0 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 68  it.** escapes th
1e400 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63  e double-quote c
1e410 68 61 72 61 63 74 65 72 20 69 6e 73 74 65 61 64  haracter instead
1e420 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d 71   of the single-q
1e430 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 65  uote.** characte
1e440 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20 66  r.)^  The "%w" f
1e450 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1e460 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
1e470 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69 6e   safely insertin
1e480 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 63  g.** table and c
1e490 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f  olumn names into
1e4a0 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20 53   a constructed S
1e4b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
1e4c0 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
1e4d0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1e4e0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
1e4f0 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
1e500 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
1e510 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
1e520 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
1e530 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
1e540 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
1e550 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
1e560 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
1e570 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
1e580 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
1e590 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1e5a0 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
1e5b0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1e5c0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
1e5d0 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
1e5e0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
1e5f0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1e600 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72  har*, ...);.char
1e610 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69   *sqlite3_vsnpri
1e620 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1e630 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1e640 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  st);../*.** CAPI
1e650 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
1e660 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
1e670 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
1e680 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
1e690 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
1e6a0 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
1e6b0 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
1e6c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1e6d0 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
1e6e0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
1e6f0 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
1e700 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
1e710 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
1e720 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
1e730 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
1e740 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
1e750 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
1e760 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1e770 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
1e780 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
1e790 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e7a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1e7b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1e7c0 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
1e7d0 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
1e7e0 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
1e7f0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
1e800 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
1e810 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e820 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
1e830 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
1e840 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
1e850 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
1e860 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
1e870 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
1e880 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
1e890 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
1e8a0 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
1e8b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e8c0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
1e8d0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1e8e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1e8f0 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74 69  alloc64(N) routi
1e900 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69  ne works just li
1e910 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ke.** sqlite3_ma
1e920 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20 74  lloc(N) except t
1e930 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73 69  hat N is an unsi
1e940 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74 65  gned 64-bit inte
1e950 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
1e960 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62 69  f a signed 32-bi
1e970 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
1e980 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
1e990 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20  3_free() with a 
1e9a0 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73  pointer previous
1e9b0 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ly returned.** b
1e9c0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1e9d0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1e9e0 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73  alloc() releases
1e9f0 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a   that memory so.
1ea00 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  ** that it might
1ea10 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68   be reused.  ^Th
1ea20 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  e sqlite3_free()
1ea30 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61   routine is.** a
1ea40 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c   no-op if is cal
1ea50 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
1ea60 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e  pointer.  Passin
1ea70 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  g a NULL pointer
1ea80 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  .** to sqlite3_f
1ea90 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73  ree() is harmles
1eaa0 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20  s.  After being 
1eab0 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a  freed, memory.**
1eac0 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20   should neither 
1ead0 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74  be read nor writ
1eae0 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69  ten.  Even readi
1eaf0 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72  ng previously fr
1eb00 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69  eed.** memory mi
1eb10 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20  ght result in a 
1eb20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
1eb30 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  lt or other seve
1eb40 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d  re error..** Mem
1eb50 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20  ory corruption, 
1eb60 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1eb70 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73  ault, or other s
1eb80 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  evere error.** m
1eb90 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73  ight result if s
1eba0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1ebb0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e   called with a n
1ebc0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  on-NULL pointer 
1ebd0 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  that.** was not 
1ebe0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
1ebf0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1ec00 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1ec10 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  c()..**.** ^The 
1ec20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ec30 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 61  X,N) interface a
1ec40 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
1ec50 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
1ec60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58  ory allocation X
1ec70 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
1ec80 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  N bytes..** ^If 
1ec90 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20  the X parameter 
1eca0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1ecb0 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20  oc(X,N).** is a 
1ecc0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1ecd0 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
1ece0 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
1ecf0 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1ed00 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20  3_malloc(N)..** 
1ed10 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65  ^If the N parame
1ed20 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1ed30 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a  ealloc(X,N) is z
1ed40 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
1ed50 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
1ed60 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
1ed70 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
1ed80 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
1ed90 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69  ree(X)..** ^sqli
1eda0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1edb0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1edc0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
1edd0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
1ede0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1edf0 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
1ee00 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74   if insufficient
1ee10 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69 6c   memory is avail
1ee20 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69  able..** ^If M i
1ee30 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
1ee40 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1ee50 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
1ee60 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
1ee70 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1ee80 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
1ee90 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
1eea0 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
1eeb0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1eec0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61  3_realloc(X,N) a
1eed0 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
1eee0 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
1eef0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1ef00 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65  _realloc(X,N) re
1ef10 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e  turns NULL and N
1ef20 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68   is positive, th
1ef30 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20  en the.** prior 
1ef40 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f  allocation is no
1ef50 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  t freed..**.** ^
1ef60 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1ef70 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65 72  loc64(X,N) inter
1ef80 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65 20  faces works the 
1ef90 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74  same as.** sqlit
1efa0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1efb0 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73  except that N is
1efc0 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e   a 64-bit unsign
1efd0 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65  ed integer inste
1efe0 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69  ad.** of a 32-bi
1eff0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
1f000 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73  ..**.** ^If X is
1f010 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1f020 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79 20  tion previously 
1f030 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
1f040 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a  lite3_malloc(),.
1f050 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1f060 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  c64(), sqlite3_r
1f070 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c  ealloc(), or sql
1f080 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29  ite3_realloc64()
1f090 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
1f0a0 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
1f0b0 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  ns the size of t
1f0c0 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hat memory alloc
1f0d0 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a  ation in bytes..
1f0e0 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  ** ^The value re
1f0f0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1f100 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68 74  3_msize(X) might
1f110 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
1f120 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66  the number.** of
1f130 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65 64   bytes requested
1f140 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f   when X was allo
1f150 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69 73  cated.  ^If X is
1f160 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1f170 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
1f180 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73  msize(X) returns
1f190 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f 69   zero.  If X poi
1f1a0 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67  nts to something
1f1b0 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20   that is not.** 
1f1c0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
1f1d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1f1e0 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f 69  on, or if it poi
1f1f0 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c  nts to a formerl
1f200 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72  y.** valid memor
1f210 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61  y allocation tha
1f220 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20 66  t has now been f
1f230 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62  reed, then the b
1f240 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71  ehavior.** of sq
1f250 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 69  lite3_msize(X) i
1f260 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
1f270 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75 6c  possibly harmful
1f280 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1f290 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
1f2a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f2b0 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
1f2c0 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c(),.** sqlite3_
1f2d0 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20  malloc64(), and 
1f2e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1f2f0 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  4().** is always
1f300 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
1f310 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
1f320 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61  oundary, or to a
1f330 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64  .** 4 byte bound
1f340 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49  ary if the [SQLI
1f350 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45  TE_4_BYTE_ALIGNE
1f360 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c  D_MALLOC] compil
1f370 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
1f380 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1f390 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
1f3a0 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
1f3b0 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
1f3c0 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
1f3d0 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
1f3e0 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
1f3f0 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
1f400 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
1f410 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
1f420 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
1f430 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
1f440 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
1f450 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
1f460 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
1f470 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
1f480 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
1f490 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
1f4a0 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69  ** Prior to SQLi
1f4b0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31  te version 3.7.1
1f4c0 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f  0, the Windows O
1f4d0 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
1f4e0 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20  r called.** the 
1f4f0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
1f500 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
1f510 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
1f520 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
1f530 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
1f540 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
1f550 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
1f560 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
1f570 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
1f580 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
1f590 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
1f5a0 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
1f5b0 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
1f5c0 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64  on errors were d
1f5d0 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
1f5e0 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74  they were report
1f5f0 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
1f600 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
1f610 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
1f620 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
1f630 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
1f640 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
1f650 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
1f660 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
1f670 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1f680 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
1f690 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
1f6a0 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
1f6b0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
1f6c0 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
1f6d0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1f6e0 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
1f6f0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
1f700 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
1f710 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
1f720 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
1f730 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
1f740 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
1f750 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
1f760 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
1f770 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
1f780 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
1f790 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
1f7a0 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
1f7b0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
1f7c0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
1f7d0 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
1f7e0 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
1f7f0 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  64(sqlite3_uint6
1f800 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  4);.void *sqlite
1f810 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
1f820 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c   int);.void *sql
1f830 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76  ite3_realloc64(v
1f840 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  oid*, sqlite3_ui
1f850 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt64);.void sqli
1f860 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
1f870 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20  .sqlite3_uint64 
1f880 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f  sqlite3_msize(vo
1f890 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1f8a0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1f8b0 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
1f8c0 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  cs.**.** SQLite 
1f8d0 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
1f8e0 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
1f8f0 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
1f900 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
1f910 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
1f920 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
1f930 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
1f940 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1f950 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
1f960 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
1f970 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1f980 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
1f990 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  em..**.** ^The [
1f9a0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1f9b0 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
1f9c0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
1f9d0 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66  r of bytes.** of
1f9e0 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
1f9f0 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d  y outstanding (m
1fa00 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
1fa10 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20  freed)..** ^The 
1fa20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1fa30 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75  highwater()] rou
1fa40 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1fa50 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75   maximum.** valu
1fa60 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
1fa70 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e  mory_used()] sin
1fa80 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  ce the high-wate
1fa90 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61  r mark.** was la
1faa0 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20  st reset.  ^The 
1fab0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
1fac0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
1fad0 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a  ry_used()] and.*
1fae0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1faf0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
1fb00 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68  nclude any overh
1fb10 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20  ead.** added by 
1fb20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d  SQLite in its im
1fb30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1fb40 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1fb50 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f  )],.** but not o
1fb60 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79  verhead added by
1fb70 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79   the any underly
1fb80 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61  ing system libra
1fb90 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  ry.** routines t
1fba0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
1fbb0 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
1fbc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
1fbd0 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  ry high-water ma
1fbe0 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74  rk is reset to t
1fbf0 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
1fc00 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
1fc10 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69  memory_used()] i
1fc20 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
1fc30 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  e parameter to.*
1fc40 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1fc50 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
1fc60 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61  s true.  ^The va
1fc70 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
1fc80 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
1fc90 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d  ry_highwater(1)]
1fca0 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74   is the high-wat
1fcb0 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72  er mark.** prior
1fcc0 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
1fcd0 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
1fce0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1fcf0 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
1fd00 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1fd10 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1fd20 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
1fd30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1fd40 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
1fd50 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
1fd60 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  r.**.** SQLite c
1fd70 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
1fd80 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
1fd90 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
1fda0 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
1fdb0 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
1fdc0 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52  andom [ROWID | R
1fdd0 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65  OWIDs] when inse
1fde0 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
1fdf0 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
1fe00 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
1fe10 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
1fe20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d  possible [ROWID]
1fe30 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61  .  The PRNG is a
1fe40 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  lso used for.** 
1fe50 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e  the build-in ran
1fe60 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d  dom() and random
1fe70 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74  blob() SQL funct
1fe80 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65  ions.  This inte
1fe90 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20  rface allows.** 
1fea0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20  applications to 
1feb0 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20  access the same 
1fec0 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70  PRNG for other p
1fed0 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  urposes..**.** ^
1fee0 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
1fef0 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
1ff00 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
1ff10 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
1ff20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61 72  P..** ^The P par
1ff30 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61 20  ameter can be a 
1ff40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1ff50 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f 75  .** ^If this rou
1ff60 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 65  tine has not bee
1ff70 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61 6c  n previously cal
1ff80 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70 72  led or if the pr
1ff90 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68  evious.** call h
1ffa0 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f  ad N less than o
1ffb0 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ne or a NULL poi
1ffc0 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65 6e  nter for P, then
1ffd0 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20   the PRNG is.** 
1ffe0 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
1fff0 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
20000 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
20010 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a  mness method of.
20020 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  ** the default [
20030 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
20040 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ect..** ^If the 
20050 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
20060 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
20070 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d  d an N of 1 or m
20080 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e  ore and a.** non
20090 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68 65  -NULL P then the
200a0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
200b0 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
200c0 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
200d0 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
200e0 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
200f0 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
20100 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
20110 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
20120 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c  andomness(int N,
20130 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a   void *P);../*.*
20140 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
20150 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69  ile-Time Authori
20160 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  zation Callbacks
20170 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
20180 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
20190 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
201a0 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  s an authorizer 
201b0 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
201c0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
201d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
201e0 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
201f0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
20200 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74  ent..** ^The aut
20210 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20220 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
20230 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
20240 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
20250 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
20260 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
20270 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
20280 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
20290 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
202a0 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
202b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
202c0 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76  16_v2()].  ^At v
202d0 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
202e0 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
202f0 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
20300 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
20310 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
20320 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
20330 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
20340 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20350 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
20360 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
20370 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
20380 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
20390 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
203a0 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
203b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
203c0 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
203d0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
203e0 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
203f0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
20400 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
20410 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
20420 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
20430 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
20440 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
20450 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
20460 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
20470 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
20480 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
20490 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
204a0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
204b0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
204c0 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
204d0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
204e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
204f0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
20500 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
20510 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
20520 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
20530 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
20540 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
20550 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
20560 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
20570 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
20580 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
20590 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
205a0 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
205b0 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
205c0 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
205d0 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
205e0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
205f0 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
20600 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
20610 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
20620 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
20630 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
20640 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
20650 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
20660 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
20670 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
20680 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
20690 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
206a0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
206b0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
206c0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
206d0 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
206e0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
206f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
20700 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
20710 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
20720 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
20730 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
20740 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
20750 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
20760 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
20770 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
20780 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
20790 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
207a0 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
207b0 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
207c0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
207d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
207e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
207f0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
20800 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
20810 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
20820 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
20830 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
20840 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
20850 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
20860 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
20870 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
20880 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
20890 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
208a0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
208b0 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
208c0 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
208d0 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
208e0 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
208f0 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
20900 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
20910 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
20920 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
20930 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
20940 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
20950 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
20960 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
20970 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
20980 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
20990 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
209a0 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
209b0 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49  f a table..** ^I
209c0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
209d0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c  e is [SQLITE_DEL
209e0 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c  ETE] and the cal
209f0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
20a00 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
20a10 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54   then the [DELET
20a20 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  E] operation pro
20a30 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a  ceeds but the.**
20a40 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
20a50 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61  ization] is disa
20a60 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77  bled and all row
20a70 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e  s are deleted in
20a80 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a  dividually..**.*
20a90 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
20aa0 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
20ab0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
20ac0 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
20ad0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
20ae0 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
20af0 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
20b00 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
20b10 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
20b20 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
20b30 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
20b40 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
20b50 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
20b60 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
20b70 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
20b80 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
20b90 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
20ba0 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
20bb0 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
20bc0 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
20bd0 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
20be0 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
20bf0 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
20c00 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
20c10 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
20c20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
20c30 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
20c40 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
20c50 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
20c60 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
20c70 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
20c80 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
20c90 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
20ca0 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
20cb0 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
20cc0 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
20cd0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
20ce0 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
20cf0 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
20d00 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
20d10 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
20d20 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
20d30 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
20d40 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
20d50 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
20d60 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
20d70 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
20d80 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
20d90 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
20da0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
20db0 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
20dc0 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
20dd0 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
20de0 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
20df0 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
20e00 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
20e10 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
20e20 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  * ^(Only a singl
20e30 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
20e40 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
20e50 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
20e60 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
20e70 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
20e80 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
20e90 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
20ea0 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
20eb0 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73  us call.)^  ^Dis
20ec0 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
20ed0 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
20ee0 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
20ef0 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
20f00 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
20f10 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
20f20 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
20f30 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
20f40 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
20f50 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
20f60 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
20f70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
20f80 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74   invoked the aut
20f90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20fa0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
20fb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20fc0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
20fd0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
20fe0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
20ff0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21000 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
21010 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
21020 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
21030 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ph..**.** ^When 
21040 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21050 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74  _v2()] is used t
21060 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74  o prepare a stat
21070 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74  ement, the.** st
21080 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65  atement might be
21090 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72   re-prepared dur
210a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
210b0 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a  p()] due to a .*
210c0 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  * schema change.
210d0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70    Hence, the app
210e0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
210f0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  ensure that the.
21100 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f  ** correct autho
21110 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
21120 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20  emains in place 
21130 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69  during the [sqli
21140 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
21150 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
21160 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
21170 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
21180 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
21190 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
211a0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
211b0 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
211c0 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
211d0 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
211e0 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
211f0 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
21200 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a  step()], unless.
21210 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20  ** as stated in 
21220 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
21230 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f  agraph, sqlite3_
21240 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a  step() invokes.*
21250 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
21260 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70  e_v2() to reprep
21270 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20  are a statement 
21280 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63  after a schema c
21290 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  hange..*/.int sq
212a0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
212b0 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
212c0 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
212d0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
212e0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
212f0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
21300 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
21310 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
21320 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
21330 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
21340 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
21350 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
21360 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
21370 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21380 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
21390 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
213a0 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
213b0 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
213c0 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
213d0 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
213e0 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
213f0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
21400 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
21410 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
21420 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
21430 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
21440 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
21450 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
21460 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
21470 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
21480 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69   SQLITE_IGNORE i
21490 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61  s also used as a
214a0 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c   [conflict resol
214b0 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72  ution mode].** r
214c0 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65  eturned from the
214d0 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f   [sqlite3_vtab_o
214e0 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e  n_conflict()] in
214f0 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66  terface..*/.#def
21500 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
21510 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
21520 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
21530 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
21540 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21550 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
21560 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
21570 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
21580 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
21590 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
215a0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
215b0 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
215c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
215d0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
215e0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
215f0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
21600 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
21610 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
21620 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
21630 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
21640 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
21650 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
21660 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
21670 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
21680 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
21690 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
216a0 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
216b0 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
216c0 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
216d0 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
216e0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
216f0 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
21700 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
21710 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
21720 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
21730 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
21740 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
21750 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
21760 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
21770 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
21780 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
21790 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
217a0 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
217b0 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
217c0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
217d0 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
217e0 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
217f0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
21800 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
21810 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
21820 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
21830 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
21840 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
21850 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
21860 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
21870 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
21880 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
21890 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
218a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
218b0 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
218c0 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
218d0 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
218e0 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
218f0 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
21900 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
21910 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
21920 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
21930 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
21940 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
21950 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
21960 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21970 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21980 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
21990 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
219a0 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
219b0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
219c0 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
219d0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
219e0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
219f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21a00 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
21a10 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
21a20 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
21a30 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21a40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21a50 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
21a60 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
21a70 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
21a80 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21a90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21aa0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
21ab0 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
21ac0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21ad0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21ae0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21af0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
21b00 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
21b10 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
21b20 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
21b30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21b40 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
21b50 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
21b60 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
21b70 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21b80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21b90 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
21ba0 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
21bb0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
21bc0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21bd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21be0 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
21bf0 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
21c00 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
21c10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21c20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
21c30 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
21c40 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
21c50 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
21c60 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21c70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
21c80 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
21c90 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
21ca0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
21cb0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21cc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21cd0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
21ce0 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
21cf0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
21d00 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21d10 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
21d20 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
21d30 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
21d40 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
21d50 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
21d60 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
21d70 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
21d80 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
21d90 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
21da0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21db0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
21dc0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
21dd0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
21de0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
21df0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21e00 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
21e10 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
21e20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
21e30 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21e40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21e50 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
21e60 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
21e70 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
21e80 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
21e90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21ea0 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
21eb0 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
21ec0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
21ed0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21ee0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21ef0 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
21f00 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
21f10 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
21f20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21f30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21f40 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
21f50 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
21f60 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
21f70 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
21f80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21f90 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
21fa0 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
21fb0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21fc0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
21fd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21fe0 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
21ff0 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
22000 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
22010 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22020 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22030 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
22040 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
22050 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
22060 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22070 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22080 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
22090 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
220a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
220b0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
220c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
220d0 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
220e0 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
220f0 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
22100 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22110 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
22120 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
22130 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
22140 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
22150 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22160 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
22170 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
22180 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
22190 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
221a0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
221b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
221c0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
221d0 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
221e0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
221f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22200 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
22210 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
22220 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
22230 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22240 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22250 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22260 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
22270 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
22280 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
22290 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
222a0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
222b0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
222c0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
222d0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
222e0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
222f0 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
22300 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
22310 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
22320 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
22330 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
22340 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
22350 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
22360 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
22370 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
22380 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
22390 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
223a0 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
223b0 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
223c0 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
223d0 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20  ITE_RECURSIVE   
223e0 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a           33   /*
223f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22400 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22410 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
22420 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
22430 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
22440 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
22450 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
22460 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
22470 20 64 65 70 72 65 63 61 74 65 64 2e 20 55 73 65   deprecated. Use
22480 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72   the [sqlite3_tr
22490 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  ace_v2()] interf
224a0 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f  ace.** instead o
224b0 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20 64  f the routines d
224c0 65 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a 2a  escribed here..*
224d0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
224e0 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
224f0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
22500 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
22510 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
22520 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
22530 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
22540 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
22550 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
22560 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
22570 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
22580 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
22590 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
225a0 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
225b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
225c0 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
225d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
225e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
225f0 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
22600 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
22610 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
22620 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
22630 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
22640 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
22650 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
22660 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
22670 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
22680 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
22690 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
226a0 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
226b0 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
226c0 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
226d0 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
226e0 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
226f0 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
22700 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
22710 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
22720 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er.)^.**.** The 
22730 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
22740 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
22750 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61  e-time option ca
22760 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d  n be used to lim
22770 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68  it.** the length
22780 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d   of [bound param
22790 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20  eter] expansion 
227a0 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66  in the output of
227b0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
227c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
227d0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
227e0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
227f0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
22800 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
22810 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
22820 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54  nt finishes.  ^T
22830 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
22840 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
22850 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
22860 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
22870 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
22880 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
22890 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
228a0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
228b0 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20  k to run.  ^The 
228c0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
228d0 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75  .** time is in u
228e0 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  nits of nanoseco
228f0 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65  nds, however the
22900 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
22910 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e  ntation.** is on
22920 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69  ly capable of mi
22930 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75  llisecond resolu
22940 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20  tion so the six 
22950 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
22960 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74  t.** digits in t
22970 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e  he time are mean
22980 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65  ingless.  Future
22990 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
229a0 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f  ite.** might pro
229b0 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73  vide greater res
229c0 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70  olution on the p
229d0 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b  rofiler callback
229e0 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
229f0 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63  3_profile() func
22a00 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72  tion is consider
22a10 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
22a20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63  and is.** subjec
22a30 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
22a40 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
22a50 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c  f SQLite..*/.SQL
22a60 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
22a70 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
22a80 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  ce(sqlite3*,.   
22a90 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
22aa0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
22ab0 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
22ac0 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
22ad0 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
22ae0 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
22af0 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
22b00 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
22b10 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
22b20 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
22b30 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54   CAPI3REF: SQL T
22b40 72 61 63 65 20 45 76 65 6e 74 20 43 6f 64 65 73  race Event Codes
22b50 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
22b60 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a  LITE_TRACE.**.**
22b70 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
22b80 20 69 64 65 6e 74 69 66 79 20 63 6c 61 73 73 65   identify classe
22b90 73 20 6f 66 20 65 76 65 6e 74 73 20 74 68 61 74  s of events that
22ba0 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f 72 65   can be monitore
22bb0 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b  d.** using the [
22bc0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
22bd0 28 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f 67 69  ()] tracing logi
22be0 63 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  c.  The third ar
22bf0 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71  gument.** to [sq
22c00 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
22c10 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f  ] is an OR-ed co
22c20 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65  mbination of one
22c30 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74   or more of.** t
22c40 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e  he following con
22c50 73 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69  stants.  ^The fi
22c60 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
22c70 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61  the trace callba
22c80 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20  ck.** is one of 
22c90 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f  the following co
22ca0 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e  nstants..**.** N
22cb0 65 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74  ew tracing const
22cc0 61 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64 65  ants may be adde
22cd0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
22ce0 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74  ases..**.** ^A t
22cf0 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61  race callback ha
22d00 73 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73  s four arguments
22d10 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c  : xCallback(T,C,
22d20 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20  P,X)..** ^The T 
22d30 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
22d40 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 74  of the integer t
22d50 79 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e  ype codes above.
22d60 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d  .** ^The C argum
22d70 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ent is a copy of
22d80 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69   the context poi
22d90 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 20 61  nter passed in a
22da0 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
22db0 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
22dc0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
22dd0 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58  ..** The P and X
22de0 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70   arguments are p
22df0 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65  ointers whose me
22e00 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e  anings depend on
22e10 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a   T..**.** <dl>.*
22e20 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
22e30 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49  _STMT]] <dt>SQLI
22e40 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64  TE_TRACE_STMT</d
22e50 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
22e60 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20  LITE_TRACE_STMT 
22e70 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
22e80 6b 65 64 20 77 68 65 6e 20 61 20 70 72 65 70 61  ked when a prepa
22e90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
22ea0 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 72 75   first begins ru
22eb0 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62  nning and possib
22ec0 6c 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65  ly at other time
22ed0 73 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  s during the.** 
22ee0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
22ef0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
22f00 65 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74 20  ent, such as at 
22f10 74 68 65 20 73 74 61 72 74 20 6f 66 20 65 61 63  the start of eac
22f20 68 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62  h.** trigger sub
22f30 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20  program. ^The P 
22f40 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
22f50 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
22f60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22f70 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67  ent]. ^The X arg
22f80 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
22f90 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  er to a string w
22fa0 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75  hich.** is the u
22fb0 6e 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65  nexpanded SQL te
22fc0 78 74 20 6f 66 20 74 68 65 20 70 72 65 70 61 72  xt of the prepar
22fd0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20  ed statement or 
22fe0 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a  an SQL comment .
22ff0 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
23000 73 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e  s the invocation
23010 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20   of a trigger.  
23020 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61  ^The callback ca
23030 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65  n compute.** the
23040 20 73 61 6d 65 20 74 65 78 74 20 74 68 61 74 20   same text that 
23050 77 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20  would have been 
23060 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
23070 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
23080 74 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65  trace()].** inte
23090 72 66 61 63 65 20 62 79 20 75 73 69 6e 67 20 74  rface by using t
230a0 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68  he X argument wh
230b0 65 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74 68  en X begins with
230c0 20 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69   "--" and invoki
230d0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
230e0 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20  xpanded_sql(P)] 
230f0 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
23100 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f   [[SQLITE_TRACE_
23110 50 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51  PROFILE]] <dt>SQ
23120 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
23130 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  LE</dt>.** <dd>^
23140 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
23150 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b  PROFILE callback
23160 20 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78   provides approx
23170 69 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65  imately the same
23180 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
23190 61 73 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  as is provided b
231a0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  y the [sqlite3_p
231b0 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61  rofile()] callba
231c0 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72  ck..** ^The P ar
231d0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
231e0 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70  ter to the [prep
231f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
23200 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67  and the.** X arg
23210 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20  ument points to 
23220 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  a 64-bit integer
23230 20 77 68 69 63 68 20 69 73 20 74 68 65 20 65 73   which is the es
23240 74 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68  timated of.** th
23250 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f  e number of nano
23260 73 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20  second that the 
23270 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23280 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a  nt took to run..
23290 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54  ** ^The SQLITE_T
232a0 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c  RACE_PROFILE cal
232b0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
232c0 20 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   when the statem
232d0 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a  ent finishes..**
232e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
232f0 43 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c  CE_ROW]] <dt>SQL
23300 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64  ITE_TRACE_ROW</d
23310 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
23320 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63  LITE_TRACE_ROW c
23330 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
23340 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 70 72  ed whenever a pr
23350 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
23360 65 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61 20  ent generates a 
23370 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65  single row of re
23380 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20  sult.  .** ^The 
23390 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
233a0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
233b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
233c0 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58  nt] and the.** X
233d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75   argument is unu
233e0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  sed..**.** [[SQL
233f0 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d  ITE_TRACE_CLOSE]
23400 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
23410 43 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a  CE_CLOSE</dt>.**
23420 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f   <dd>^An SQLITE_
23430 54 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c  TRACE_CLOSE call
23440 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
23450 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a  when a database.
23460 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  ** connection cl
23470 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  oses..** ^The P 
23480 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
23490 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
234a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
234b0 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  n] object.** and
234c0 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20   the X argument 
234d0 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f  is unused..** </
234e0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
234f0 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54  QLITE_TRACE_STMT
23500 20 20 20 20 20 20 20 30 78 30 31 0a 23 64 65 66         0x01.#def
23510 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
23520 5f 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32  _PROFILE    0x02
23530 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23540 54 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20  TRACE_ROW       
23550 20 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51   0x04.#define SQ
23560 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
23570 20 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a        0x08../*.*
23580 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
23590 54 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45  Trace Hook.** ME
235a0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
235b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
235c0 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c  _trace_v2(D,M,X,
235d0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  P) interface reg
235e0 69 73 74 65 72 73 20 61 20 74 72 61 63 65 20 63  isters a trace c
235f0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
23600 69 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64  ion X against [d
23610 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23620 6f 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f  on] D, using pro
23630 70 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20  perty mask M.** 
23640 61 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e  and context poin
23650 74 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20  ter P.  ^If the 
23660 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a  X callback is.**
23670 20 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20   NULL or if the 
23680 4d 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20  M mask is zero, 
23690 74 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20  then tracing is 
236a0 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a  disabled.  The.*
236b0 2a 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  * M argument sho
236c0 75 6c 64 20 62 65 20 74 68 65 20 62 69 74 77 69  uld be the bitwi
236d0 73 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61  se OR-ed combina
236e0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20  tion of.** zero 
236f0 6f 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f  or more [SQLITE_
23700 54 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73  TRACE] constants
23710 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61  ..**.** ^Each ca
23720 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c  ll to either sql
23730 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20  ite3_trace() or 
23740 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
23750 28 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a  () overrides .**
23760 20 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70   (cancels) any p
23770 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71  rior calls to sq
23780 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72  lite3_trace() or
23790 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
237a0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  2()..**.** ^The 
237b0 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  X callback is in
237c0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
237d0 6e 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73  ny of the events
237e0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a   identified by .
237f0 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e  ** mask M occur.
23800 20 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72    ^The integer r
23810 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
23820 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
23830 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67   currently.** ig
23840 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68  nored, though th
23850 69 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e  is may change in
23860 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
23870 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  .  Callback.** i
23880 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
23890 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72  hould return zer
238a0 6f 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75  o to ensure futu
238b0 72 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  re compatibility
238c0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65  ..**.** ^A trace
238d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
238e0 6f 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20 61  oked with four a
238f0 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61  rguments: callba
23900 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20  ck(T,C,P,X)..** 
23910 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20  ^The T argument 
23920 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53  is one of the [S
23930 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20  QLITE_TRACE].** 
23940 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64  constants to ind
23950 69 63 61 74 65 20 77 68 79 20 74 68 65 20 63 61  icate why the ca
23960 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b  llback was invok
23970 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72  ed..** ^The C ar
23980 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79  gument is a copy
23990 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20   of the context 
239a0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20  pointer..** The 
239b0 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74  P and X argument
239c0 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77  s are pointers w
239d0 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65  hose meanings de
239e0 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a  pend on T..**.**
239f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61   The sqlite3_tra
23a00 63 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  ce_v2() interfac
23a10 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  e is intended to
23a20 20 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67   replace the leg
23a30 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
23a40 73 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  s [sqlite3_trace
23a50 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
23a60 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74  _profile()], bot
23a70 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72  h of which.** ar
23a80 65 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f  e deprecated..*/
23a90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61  .int sqlite3_tra
23aa0 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  ce_v2(.  sqlite3
23ab0 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d  *,.  unsigned uM
23ac0 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c  ask,.  int(*xCal
23ad0 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c  lback)(unsigned,
23ae0 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64  void*,void*,void
23af0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78  *),.  void *pCtx
23b00 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
23b10 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
23b20 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
23b30 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
23b40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
23b50 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
23b60 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
23b70 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
23b80 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
23b90 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
23ba0 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
23bb0 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
23bc0 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
23bd0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
23be0 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
23bf0 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
23c00 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
23c10 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
23c20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
23c30 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
23c40 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
23c50 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
23c60 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
23c70 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
23c80 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
23c90 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
23ca0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
23cb0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
23cc0 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
23cd0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
23ce0 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
23cf0 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70  ter N is the app
23d00 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20  roximate number 
23d10 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
23d20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
23d30 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
23d40 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
23d50 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
23d60 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
23d70 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e  e callback X.  ^
23d80 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
23d90 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70  n one then the p
23da0 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c  rogress.** handl
23db0 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  er is disabled..
23dc0 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
23dd0 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
23de0 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
23df0 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
23e00 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
23e10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
23e20 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
23e30 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
23e40 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
23e50 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
23e60 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
23e70 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
23e80 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
23e90 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
23ea0 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
23eb0 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
23ec0 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
23ed0 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
23ee0 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
23ef0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
23f00 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
23f10 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
23f20 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
23f30 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
23f40 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
23f50 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
23f60 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
23f70 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
23f80 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
23f90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
23fa0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
23fb0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
23fc0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
23fd0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
23fe0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
23ff0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
24000 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
24010 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
24020 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
24030 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
24040 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
24050 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
24060 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
24070 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
24080 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
24090 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
240a0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
240b0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
240c0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
240d0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
240e0 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
240f0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
24100 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
24110 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
24120 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53  nnection.** CONS
24130 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
24140 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
24150 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
24160 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
24170 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64  ile as specified
24180 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65   by the .** file
24190 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
241a0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
241b0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
241c0 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
241d0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
241e0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
241f0 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
24200 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
24210 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
24220 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
24230 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
24240 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24250 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
24260 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
24270 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
24280 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
24290 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
242a0 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
242b0 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
242c0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
242d0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
242e0 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
242f0 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
24300 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
24310 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
24320 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
24330 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
24340 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
24350 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
24360 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
24370 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
24380 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
24390 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
243a0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
243b0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
243c0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
243d0 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
243e0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
243f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
24400 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
24410 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
24420 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
24430 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
24440 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
24450 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
24460 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
24470 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
24480 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
24490 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
244a0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
244b0 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  ng will be UTF-8
244c0 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63   for databases c
244d0 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
244e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
244f0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
24500 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75  2().  ^The defau
24510 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
24520 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65  databases.** cre
24530 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74  ated using sqlit
24540 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c  e3_open16() will
24550 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68   be UTF-16 in th
24560 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
24570 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  der..**.** Wheth
24580 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
24590 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
245a0 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
245b0 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
245c0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
245d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
245e0 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
245f0 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
24600 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
24610 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
24620 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
24630 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
24640 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
24650 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
24660 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
24670 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
24680 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
24690 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
246a0 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
246b0 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
246c0 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
246d0 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
246e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
246f0 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
24700 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
24710 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24720 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
24730 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
24740 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
24750 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
24760 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
24770 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
24780 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
24790 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
247a0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
247b0 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
247c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
247d0 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f  VATECACHE], and/
247e0 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
247f0 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a  URI] flags:)^.**
24800 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
24810 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
24820 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
24830 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
24840 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
24850 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
24860 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
24870 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
24880 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
24890 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
248a0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
248b0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
248c0 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
248d0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
248e0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
248f0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
24900 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
24910 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
24920 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
24930 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
24940 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
24950 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
24960 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
24970 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
24980 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
24990 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
249a0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
249b0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
249c0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
249d0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
249e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
249f0 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATE]</dt>.** <dd
24a00 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
24a10 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
24a20 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c  ing and writing,
24a30 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20   and is created 
24a40 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
24a50 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
24a60 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
24a70 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
24a80 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
24a90 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
24aa0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
24ab0 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  16().</dd>)^.** 
24ac0 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
24ad0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
24ae0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
24af0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
24b00 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
24b10 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
24b20 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  ove optionally c
24b30 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68  ombined with oth
24b40 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  er.** [SQLITE_OP
24b50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51  EN_READONLY | SQ
24b60 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73  LITE_OPEN_* bits
24b70 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ].** then the be
24b80 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
24b90 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
24ba0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
24bb0 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
24bc0 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
24bd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24be0 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
24bf0 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
24c00 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
24c10 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
24c20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
24c30 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
24c40 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
24c50 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
24c60 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
24c70 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
24c80 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
24c90 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
24ca0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24cb0 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
24cc0 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
24cd0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
24ce0 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
24cf0 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
24d00 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
24d10 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
24d20 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
24d30 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
24d40 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
24d50 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
24d60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24d70 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
24d80 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
24d90 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
24da0 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
24db0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
24dc0 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
24dd0 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
24de0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
24df0 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
24e00 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
24e10 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
24e20 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
24e30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
24e40 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
24e50 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
24e60 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
24e70 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
24e80 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
24e90 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
24ea0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
24eb0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
24ec0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
24ed0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
24ee0 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
24ef0 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
24f00 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
24f10 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
24f20 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
24f30 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
24f40 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
24f50 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
24f60 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
24f70 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
24f80 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
24f90 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
24fa0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
24fb0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
24fc0 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
24fd0 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
24fe0 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
24ff0 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
25000 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
25010 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
25020 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
25030 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
25040 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
25050 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
25060 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
25070 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
25080 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
25090 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
250a0 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
250b0 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
250c0 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
250d0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
250e0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
250f0 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
25100 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
25110 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
25120 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
25130 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
25140 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
25150 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
25160 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
25170 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
25180 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
25190 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
251a0 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
251b0 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
251c0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
251d0 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
251e0 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
251f0 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
25200 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
25210 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
25220 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
25230 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
25240 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25250 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
25260 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
25270 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65  s in sqlite3_ope
25280 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69  n()]] <h3>URI Fi
25290 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  lenames</h3>.**.
252a0 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65  ** ^If [URI file
252b0 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61  name] interpreta
252c0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c  tion is enabled,
252d0 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d   and the filenam
252e0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65  e argument.** be
252f0 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a  gins with "file:
25300 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65  ", then the file
25310 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65  name is interpre
25320 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55  ted as a URI. ^U
25330 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  RI.** filename i
25340 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
25350 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
25360 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
25370 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74  ] flag is.** set
25380 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61   in the fourth a
25390 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
253a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72  e3_open_v2(), or
253b0 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65   if it has.** be
253c0 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61  en enabled globa
253d0 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53  lly using the [S
253e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
253f0 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68  ] option with th
25400 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
25410 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f  nfig()] method o
25420 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  r by the [SQLITE
25430 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c  _USE_URI] compil
25440 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
25450 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76  * As of SQLite v
25460 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52  ersion 3.7.7, UR
25470 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  I filename inter
25480 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72  pretation is tur
25490 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65  ned off.** by de
254a0 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72  fault, but futur
254b0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
254c0 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c  Lite might enabl
254d0 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a  e URI filename.*
254e0 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  * interpretation
254f0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65   by default.  Se
25500 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  e "[URI filename
25510 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  s]" for addition
25520 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
25530 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c  n..**.** URI fil
25540 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65  enames are parse
25550 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52  d according to R
25560 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65  FC 3986. ^If the
25570 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e   URI contains an
25580 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74  .** authority, t
25590 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65  hen it must be e
255a0 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73  ither an empty s
255b0 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72  tring or the str
255c0 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f  ing .** "localho
255d0 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74  st". ^If the aut
255e0 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e  hority is not an
255f0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
25600 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e   "localhost", an
25610 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65   .** error is re
25620 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61  turned to the ca
25630 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d  ller. ^The fragm
25640 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ent component of
25650 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70   a URI, if .** p
25660 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72  resent, is ignor
25670 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
25680 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20  e uses the path 
25690 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65  component of the
256a0 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65   URI as the name
256b0 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c   of the disk fil
256c0 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61  e.** which conta
256d0 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ins the database
256e0 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62  . ^If the path b
256f0 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27  egins with a '/'
25700 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20   character, .** 
25710 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72  then it is inter
25720 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73  preted as an abs
25730 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20  olute path. ^If 
25740 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f  the path does no
25750 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68  t begin .** with
25760 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20   a '/' (meaning 
25770 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
25780 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d  ty section is om
25790 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55  itted from the U
257a0 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  RI).** then the 
257b0 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65  path is interpre
257c0 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76  ted as a relativ
257d0 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e  e path. .** ^(On
257e0 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69   windows, the fi
257f0 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  rst component of
25800 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
25810 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65  h .** is a drive
25820 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28   specification (
25830 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a  e.g. "C:").)^.**
25840 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71  .** [[core URI q
25850 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d  uery parameters]
25860 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63  ].** The query c
25870 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
25880 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61  I may contain pa
25890 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72  rameters that ar
258a0 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a  e interpreted.**
258b0 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74   either by SQLit
258c0 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20  e itself, or by 
258d0 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20  a [VFS | custom 
258e0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
258f0 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61  on]..** SQLite a
25900 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20  nd its built-in 
25910 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65  [VFSes] interpre
25920 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  t the.** followi
25930 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ng query paramet
25940 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ers:.**.** <ul>.
25950 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73  **   <li> <b>vfs
25960 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22  </b>: ^The "vfs"
25970 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
25980 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66  e used to specif
25990 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a  y the name of.**
259a0 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63       a VFS objec
259b0 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20  t that provides 
259c0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
259d0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
259e0 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20  hat should.**   
259f0 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63    be used to acc
25a00 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
25a10 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e   file on disk. ^
25a20 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  If this option i
25a30 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20  s set to.**     
25a40 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
25a50 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
25a60 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20  object is used. 
25a70 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
25a80 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46  nknown.**     VF
25a90 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e  S is an error. ^
25aa0 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
25ab0 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
25ac0 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20   the vfs option 
25ad0 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e  is.**     presen
25ae0 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20  t, then the VFS 
25af0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
25b00 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72   option takes pr
25b10 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a  ecedence over.**
25b20 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70       the value p
25b30 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
25b40 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
25b50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
25b60 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
25b70 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28   <b>mode</b>: ^(
25b80 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  The mode paramet
25b90 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
25ba0 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72   either "ro", "r
25bb0 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22  w",.**     "rwc"
25bc0 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41  , or "memory". A
25bd0 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74  ttempting to set
25be0 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72   it to any other
25bf0 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20   value is.**    
25c00 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a   an error)^. .**
25c10 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73       ^If "ro" is
25c20 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
25c30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
25c40 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
25c50 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63  -only .**     ac
25c60 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66  cess, just as if
25c70 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
25c80 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67  N_READONLY] flag
25c90 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e   had been set in
25ca0 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69   the .**     thi
25cb0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
25cc0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25cd0 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f  . ^If the mode o
25ce0 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20  ption is set to 
25cf0 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68  .**     "rw", th
25d00 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
25d10 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
25d20 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f  ad-write (but no
25d30 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20  t create) .**   
25d40 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20    access, as if 
25d50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
25d60 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53  WRITE (but not S
25d70 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
25d80 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62  E) had .**     b
25d90 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20  een set. ^Value 
25da0 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c  "rwc" is equival
25db0 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62  ent to setting b
25dc0 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49  oth .**     SQLI
25dd0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
25de0 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45  E and SQLITE_OPE
25df0 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74  N_CREATE.  ^If t
25e00 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
25e10 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20  s.**     set to 
25e20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20  "memory" then a 
25e30 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20  pure [in-memory 
25e40 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e  database] that n
25e50 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20  ever reads.**   
25e60 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d    or writes from
25e70 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e   disk is used. ^
25e80 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  It is an error t
25e90 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75  o specify a valu
25ea0 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65  e for.**     the
25eb0 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
25ec0 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73  that is less res
25ed0 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68  trictive than th
25ee0 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  at specified by.
25ef0 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73  **     the flags
25f00 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74   passed in the t
25f10 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
25f20 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
25f30 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
25f40 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20  > <b>cache</b>: 
25f50 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d  ^The cache param
25f60 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
25f70 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65  to either "share
25f80 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72  d" or.**     "pr
25f90 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67  ivate". ^Setting
25fa0 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20   it to "shared" 
25fb0 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
25fc0 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20   setting the.** 
25fd0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
25fe0 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20  SHAREDCACHE bit 
25ff0 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  in the flags arg
26000 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a  ument passed to.
26010 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f  **     sqlite3_o
26020 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69  pen_v2(). ^Setti
26030 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72  ng the cache par
26040 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61  ameter to "priva
26050 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65  te" is .**     e
26060 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
26070 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  ting the SQLITE_
26080 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
26090 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49  E bit..**     ^I
260a0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
260b0 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
260c0 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61  the "cache" para
260d0 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74  meter is present
260e0 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49   in.**     a URI
260f0 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76   filename, its v
26100 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61  alue overrides a
26110 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75  ny behavior requ
26120 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67  ested by setting
26130 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
26140 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
26150 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   or SQLITE_OPEN_
26160 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67  SHAREDCACHE flag
26170 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
26180 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20  >psow</b>: ^The 
26190 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69  psow parameter i
261a0 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 65 72  ndicates whether
261b0 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20   or not the.**  
261c0 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76     [powersafe ov
261d0 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74  erwrite] propert
261e0 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e  y does or does n
261f0 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a  ot apply to the.
26200 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d  **     storage m
26210 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68  edia on which th
26220 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
26230 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20  resides..**.**  
26240 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f  <li> <b>nolock</
26250 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20  b>: ^The nolock 
26260 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
26270 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72  oolean query par
26280 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68  ameter.**     wh
26290 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62  ich if set disab
262a0 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67  les file locking
262b0 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75   in rollback jou
262c0 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69  rnal modes.  Thi
262d0 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66  s.**     is usef
262e0 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67  ul for accessing
262f0 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61   a database on a
26300 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74   filesystem that
26310 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20   does not.**    
26320 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67   support locking
26330 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74  .  Caution:  Dat
26340 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
26350 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
26360 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d   two.**     or m
26370 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72  ore processes wr
26380 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20  ite to the same 
26390 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79  database and any
263a0 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a   one of those.**
263b0 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75       processes u
263c0 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a  ses nolock=1..**
263d0 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d  .**  <li> <b>imm
263e0 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65  utable</b>: ^The
263f0 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d   immutable param
26400 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
26410 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70  n query.**     p
26420 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e  arameter that in
26430 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65  dicates that the
26440 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
26450 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20  s stored on.**  
26460 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64     read-only med
26470 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74  ia.  ^When immut
26480 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c  able is set, SQL
26490 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
264a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61   the.**     data
264b0 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74  base file cannot
264c0 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65   be changed, eve
264d0 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77  n by a process w
264e0 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20  ith higher.**   
264f0 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64    privilege, and
26500 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   so the database
26510 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d   is opened read-
26520 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63  only and all loc
26530 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20  king.**     and 
26540 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e  change detection
26550 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43   is disabled.  C
26560 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20  aution: Setting 
26570 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a  the immutable.**
26580 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e       property on
26590 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
265a0 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61   that does in fa
265b0 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65  ct change can re
265c0 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69  sult.**     in i
265d0 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72  ncorrect query r
265e0 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53  esults and/or [S
265f0 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65  QLITE_CORRUPT] e
26600 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65  rrors..**     Se
26610 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f  e also: [SQLITE_
26620 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d  IOCAP_IMMUTABLE]
26630 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c  ..**       .** <
26640 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63  /ul>.**.** ^Spec
26650 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
26660 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  n parameter in t
26670 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
26680 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e  nt of a URI is n
26690 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20  ot an.** error. 
266a0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
266b0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
266c0 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69   understand addi
266d0 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20  tional query.** 
266e0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65  parameters.  See
266f0 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74   "[query paramet
26700 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c  ers with special
26710 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69   meaning to SQLi
26720 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69  te]" for.** addi
26730 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
26740 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  on..**.** [[URI 
26750 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
26760 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65  s]] <h3>URI file
26770 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68  name examples</h
26780 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20  3>.**.** <table 
26790 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e  border="1" align
267a0 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64  =center cellpadd
267b0 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=5>.** <tr><t
267c0 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  h> URI filenames
267d0 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a   <th> Results.**
267e0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
267f0 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
26800 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
26810 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
26820 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
26830 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74  directory..** <t
26840 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
26850 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62  e/fred/data.db<b
26860 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  r>.**          f
26870 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64  ile:///home/fred
26880 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a  /data.db <br> .*
26890 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
268a0 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65  //localhost/home
268b0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
268c0 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  r> <td> .**     
268d0 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61       Open the da
268e0 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f  tabase file "/ho
268f0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
26900 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
26910 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f  le://darkstar/ho
26920 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
26930 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
26940 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72    An error. "dar
26950 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20  kstar" is not a 
26960 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f  recognized autho
26970 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  rity..** <tr><td
26980 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70   style="white-sp
26990 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a  ace:nowrap"> .**
269a0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
269b0 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32  //C:/Documents%2
269c0 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f  0and%20Settings/
269d0 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74  fred/Desktop/dat
269e0 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e  a.db.**     <td>
269f0 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f   Windows only: O
26a00 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
26a10 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73  ta.db" on fred's
26a20 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76   desktop on driv
26a30 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a  e.**          C:
26a40 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
26a50 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20  %20 escaping in 
26a60 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20  this example is 
26a70 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a  not strictly .**
26a80 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73            necess
26a90 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72  ary - space char
26aa0 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73  acters can be us
26ab0 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20  ed literally.** 
26ac0 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20           in URI 
26ad0 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74  filenames..** <t
26ae0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
26af0 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68  .db?mode=ro&cach
26b00 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a  e=private <td> .
26b10 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
26b20 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
26b30 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
26b40 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61  irectory for rea
26b50 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a  d-only access..*
26b60 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72  *          Regar
26b70 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
26b80 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63   or not shared-c
26b90 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61  ache mode is ena
26ba0 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  bled by.**      
26bb0 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65      default, use
26bc0 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65   a private cache
26bd0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
26be0 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
26bf0 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64  ta.db?vfs=unix-d
26c00 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20  otfile <td>.**  
26c10 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
26c20 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
26c30 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20  ta.db". Use the 
26c40 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69  special VFS "uni
26c50 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20  x-dotfile".**   
26c60 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73         that uses
26c70 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c   dot-files in pl
26c80 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76  ace of posix adv
26c90 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a  isory locking..*
26ca0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
26cb0 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61  data.db?mode=rea
26cc0 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20  donly <td> .**  
26cd0 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
26ce0 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20  . "readonly" is 
26cf0 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69  not a valid opti
26d00 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65  on for the "mode
26d10 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  " parameter..** 
26d20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e  </table>.**.** ^
26d30 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20  URI hexadecimal 
26d40 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
26d50 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f   (%HH) are suppo
26d60 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20  rted within the 
26d70 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72  path and.** quer
26d80 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
26d90 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63  a URI. A hexadec
26da0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
26db0 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66  ence consists of
26dc0 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69   a.** percent si
26dd0 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f  gn - "%" - follo
26de0 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74  wed by exactly t
26df0 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  wo hexadecimal d
26e00 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66  igits .** specif
26e10 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61  ying an octet va
26e20 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65  lue. ^Before the
26e30 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63   path or query c
26e40 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a  omponents of a.*
26e50 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61  * URI filename a
26e60 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20  re interpreted, 
26e70 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64  they are encoded
26e80 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64   using UTF-8 and
26e90 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63   all .** hexadec
26ea0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
26eb0 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62  ences replaced b
26ec0 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20  y a single byte 
26ed0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a  containing the.*
26ee0 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  * corresponding 
26ef0 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70  octet. If this p
26f00 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73  rocess generates
26f10 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d   an invalid UTF-
26f20 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74  8 encoding,.** t
26f30 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
26f40 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
26f50 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
26f60 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
26f70 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
26f80 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
26f90 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
26fa0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
26fb0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
26fc0 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
26fd0 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
26fe0 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
26ff0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
27000 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
27010 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
27020 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
27030 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
27040 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
27050 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
27060 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
27070 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
27080 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
27090 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ()..**.** <b>Not
270a0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e  e to Windows Run
270b0 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20  time users:</b> 
270c0 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64   The temporary d
270d0 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65  irectory must be
270e0 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f   set.** prior to
270f0 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
27100 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
27110 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f  e3_open_v2().  O
27120 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75  therwise, variou
27130 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68  s.** features th
27140 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75  at require the u
27150 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20  se of temporary 
27160 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a  files may fail..
27170 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
27180 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  [sqlite3_temp_di
27190 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20  rectory].*/.int 
271a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
271b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
271c0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
271d0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
271e0 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
271f0 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
27200 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
27210 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
27220 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
27230 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
27240 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
27250 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
27260 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
27270 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
27280 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
27290 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
272a0 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
272b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
272c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
272d0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
272e0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
272f0 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
27300 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
27310 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
27320 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
27330 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
27340 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
27350 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
27360 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
27370 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
27380 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
27390 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
273a0 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20  : Obtain Values 
273b0 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65  For URI Paramete
273c0 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  rs.**.** These a
273d0 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69  re utility routi
273e0 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56  nes, useful to V
273f0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
27400 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a  ns, that check.*
27410 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61  * to see if a da
27420 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20  tabase file was 
27430 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61  a URI that conta
27440 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20  ined a specific 
27450 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65  query .** parame
27460 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f  ter, and if so o
27470 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65  btains the value
27480 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70   of that query p
27490 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
274a0 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61  If F is the data
274b0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f  base filename po
274c0 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74  inter passed int
274d0 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65  o the xOpen() me
274e0 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46  thod of .** a VF
274f0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
27500 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20   when the flags 
27510 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
27520 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20  en() has one or 
27530 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20  .** more of the 
27540 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
27550 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
27560 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20  N_MAIN_DB] bits 
27570 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20  set and.** P is 
27580 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
27590 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c  query parameter,
275a0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
275b0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
275c0 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  ,P) returns the 
275d0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a  value of the P.*
275e0 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69  * parameter if i
275f0 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55  t exists or a NU
27600 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20  LL pointer if P 
27610 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
27620 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70  as a .** query p
27630 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20  arameter on F.  
27640 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20  If P is a query 
27650 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a  parameter of F.*
27660 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69  * has no explici
27670 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71  t value, then sq
27680 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
27690 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
276a0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
276b0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
276c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
276d0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
276e0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61  F,P,B) routine a
276f0 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73  ssumes that P is
27700 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61   a boolean.** pa
27710 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
27720 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20  rns true (1) or 
27730 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64  false (0) accord
27740 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ing to the value
27750 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73  .** of P.  The s
27760 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
27770 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
27780 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
27790 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c  1) if the.** val
277a0 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61  ue of query para
277b0 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
277c0 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c  f "yes", "true",
277d0 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a   or "on" in any.
277e0 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68  ** case or if th
277f0 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
27800 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e  ith a non-zero n
27810 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20  umber.  The .** 
27820 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
27830 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
27840 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73  nes returns fals
27850 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c  e (0) if the val
27860 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70  ue of.** query p
27870 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
27880 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73  e of "no", "fals
27890 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20  e", or "off" in 
278a0 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69  any case or.** i
278b0 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
278c0 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69  ns with a numeri
278d0 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73  c zero.  If P is
278e0 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20   not a query.** 
278f0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f  parameter on F o
27900 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  r if the value o
27910 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20  f P is does not 
27920 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65  match any of the
27930 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20  .** above, then 
27940 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
27950 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
27960 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a  ns (B!=0)..**.**
27970 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
27980 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f  _int64(F,P,D) ro
27990 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74  utine converts t
279a0 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e  he value of P in
279b0 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73  to a.** 64-bit s
279c0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
279d0 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69  d returns that i
279e0 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20  nteger, or D if 
279f0 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78  P does not.** ex
27a00 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c  ist.  If the val
27a10 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74  ue of P is somet
27a20 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
27a30 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e  an integer, then
27a40 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75  .** zero is retu
27a50 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  rned..** .** If 
27a60 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  F is a NULL poin
27a70 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ter, then sqlite
27a80 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
27a90 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  F,P) returns NUL
27aa0 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  L and.** sqlite3
27ab0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
27ac0 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20  ,B) returns B.  
27ad0 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55  If F is not a NU
27ae0 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a  LL pointer and.*
27af0 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  * is not a datab
27b00 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  ase file pathnam
27b10 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53  e pointer that S
27b20 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74  QLite passed int
27b30 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56  o the xOpen.** V
27b40 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  FS method, then 
27b50 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
27b60 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
27b70 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
27b80 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69  obably.** undesi
27b90 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  rable..*/.const 
27ba0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72  char *sqlite3_ur
27bb0 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73  i_parameter(cons
27bc0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
27bd0 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
27be0 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69  Param);.int sqli
27bf0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
27c00 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
27c10 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
27c20 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61  Param, int bDefa
27c30 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ult);.sqlite3_in
27c40 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  t64 sqlite3_uri_
27c50 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72  int64(const char
27c60 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
27c70 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
27c80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27c90 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
27ca0 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45  d Messages.** ME
27cb0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
27cc0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
27cd0 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f   recent sqlite3_
27ce0 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63  * API call assoc
27cf0 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b  iated with .** [
27d00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27d10 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74  ion] D failed, t
27d20 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
27d30 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72  errcode(D) inter
27d40 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20  face.** returns 
27d50 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73  the numeric [res
27d60 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78  ult code] or [ex
27d70 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
27d80 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20  de] for that.** 
27d90 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20  API call..** If 
27da0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
27db0 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75 63  API call was suc
27dc0 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e  cessful,.** then
27dd0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
27de0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65  e from sqlite3_e
27df0 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65  rrcode() is unde
27e00 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  fined..** ^The s
27e10 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
27e20 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74  errcode().** int
27e30 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61  erface is the sa
27e40 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69  me except that i
27e50 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
27e60 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64   the .** [extend
27e70 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
27e80 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64  even when extend
27e90 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
27ea0 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  are.** disabled.
27eb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
27ec0 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
27ed0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
27ee0 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
27ef0 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
27f00 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
27f10 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
27f20 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
27f30 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
27f40 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  vely..** ^(Memor
27f50 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
27f60 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
27f70 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
27f80 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65  ternally..** The
27f90 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
27fa0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f  s not need to wo
27fb0 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e  rry about freein
27fc0 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
27fd0 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
27fe0 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
27ff0 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
28000 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
28010 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
28020 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
28030 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
28040 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a  functions.)^.**.
28050 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28060 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61  errstr() interfa
28070 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45  ce returns the E
28080 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20  nglish-language 
28090 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73  text.** that des
280a0 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75  cribes the [resu
280b0 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46  lt code], as UTF
280c0 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  -8..** ^(Memory 
280d0 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
280e0 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
280f0 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
28100 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75  rnally.** and mu
28110 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20  st not be freed 
28120 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
28130 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  on)^..**.** When
28140 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
28150 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
28160 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d   is in use, it m
28170 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63  ight be the.** c
28180 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e  ase that a secon
28190 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f  d error occurs o
281a0 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  n a separate thr
281b0 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a  ead in between.*
281c0 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68  * the time of th
281d0 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e  e first error an
281e0 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68  d the call to th
281f0 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ese interfaces..
28200 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70  ** When that hap
28210 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64  pens, the second
28220 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
28230 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68  eported since th
28240 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ese.** interface
28250 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20  s always report 
28260 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
28270 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69  result.  To avoi
28280 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20  d.** this, each 
28290 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69  thread can obtai
282a0 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20  n exclusive use 
282b0 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
282c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
282d0 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73  * by invoking [s
282e0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
282f0 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  er]([sqlite3_db_
28300 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72  mutex](D)) befor
28310 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74  e beginning.** t
28320 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f  o use D and invo
28330 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
28340 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69  tex_leave]([sqli
28350 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
28360 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63  ) after.** all c
28370 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65  alls to the inte
28380 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65  rfaces listed he
28390 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64  re are completed
283a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e  ..**.** If an in
283b0 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
283c0 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  th SQLITE_MISUSE
283d0 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
283e0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61   interface.** wa
283f0 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72  s invoked incorr
28400 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70  ectly by the app
28410 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68  lication.  In th
28420 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20  at case, the.** 
28430 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
28440 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61  essage may or ma
28450 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f  y not be set..*/
28460 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72  .int sqlite3_err
28470 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
28480 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  );.int sqlite3_e
28490 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
284a0 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f  sqlite3 *db);.co
284b0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
284c0 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
284d0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
284e0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
284f0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
28500 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
28510 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a  errstr(int);../*
28520 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72  .** CAPI3REF: Pr
28530 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
28540 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
28550 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
28560 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
28570 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
28580 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
28590 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
285a0 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
285b0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
285c0 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62  nt that.** has b
285d0 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74  een compiled int
285e0 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e  o binary form an
285f0 64 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65  d is ready to be
28600 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a   evaluated..**.*
28610 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20  * Think of each 
28620 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
28630 20 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70   a separate comp
28640 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54  uter program.  T
28650 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
28660 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72 63  QL text is sourc
28670 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61  e code.  A prepa
28680 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  red statement ob
28690 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20  ject .** is the 
286a0 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20  compiled object 
286b0 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d  code.  All SQL m
286c0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
286d0 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61   into a.** prepa
286e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65  red statement be
286f0 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20 72  fore it can be r
28700 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  un..**.** The li
28710 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72  fe-cycle of a pr
28720 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28730 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20   object usually 
28740 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a  goes like this:.
28750 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
28760 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 70 72  i> Create the pr
28770 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28780 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
28790 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
287a0 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  2()]..** <li> Bi
287b0 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61  nd values to [pa
287c0 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
287d0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
287e0 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
287f0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
28800 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
28810 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
28820 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
28830 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
28840 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 70 72  li> Reset the pr
28850 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28860 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
28870 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
28880 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
28890 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
288a0 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
288b0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
288c0 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
288d0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
288e0 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
288f0 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66  </ol>.*/.typedef
28900 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
28910 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  stmt sqlite3_stm
28920 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
28930 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d  EF: Run-time Lim
28940 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  its.** METHOD: s
28950 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54  qlite3.**.** ^(T
28960 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
28970 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
28980 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
28990 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
289a0 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
289b0 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
289c0 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
289d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
289e0 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
289f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
28a00 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
28a10 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
28a20 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
28a30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
28a40 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
28a50 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
28a60 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
28a70 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
28a80 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
28a90 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
28aa0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
28ab0 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
28ac0 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
28ad0 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
28ae0 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
28af0 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
28b00 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
28b10 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
28b20 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
28b30 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
28b40 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
28b50 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
28b60 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
28b70 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
28b80 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
28b90 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
28ba0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
28bb0 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
28bc0 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
28bd0 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
28be0 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
28bf0 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
28c00 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
28c10 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
28c20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
28c30 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
28c40 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
28c50 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
28c60 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
28c70 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
28c80 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
28c90 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
28ca0 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
28cb0 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
28cc0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
28cd0 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
28ce0 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
28cf0 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
28d00 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
28d10 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
28d20 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
28d30 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
28d40 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
28d50 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
28d60 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
28d70 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
28d80 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
28d90 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
28da0 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
28db0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
28dc0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
28dd0 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
28de0 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
28df0 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
28e00 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
28e10 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
28e20 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
28e30 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
28e40 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
28e50 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
28e60 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
28e70 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
28e80 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
28e90 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
28ea0 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
28eb0 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
28ec0 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
28ed0 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
28ee0 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
28ef0 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
28f00 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
28f10 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
28f20 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
28f30 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
28f40 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
28f50 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
28f60 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
28f70 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
28f80 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
28f90 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
28fa0 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
28fb0 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
28fc0 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
28fd0 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
28fe0 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
28ff0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
29000 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
29010 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
29020 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
29030 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
29040 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
29050 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
29060 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
29070 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
29080 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
29090 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
290a0 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
290b0 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
290c0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
290d0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
290e0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
290f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
29100 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
29110 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
29120 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
29130 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
29140 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
29150 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
29160 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
29170 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
29180 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
29190 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
291a0 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
291b0 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
291c0 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
291d0 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
291e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
291f0 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
29200 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
29210 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
29220 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
29230 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
29240 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
29250 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
29260 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
29270 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
29280 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
29290 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
292a0 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
292b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
292c0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
292d0 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
292e0 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
292f0 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
29300 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
29310 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
29320 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
29330 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
29340 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
29350 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
29360 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
29370 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
29380 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
29390 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
293a0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
293b0 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
293c0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
293d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
293e0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
293f0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
29400 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
29410 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
29420 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
29430 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
29440 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
29450 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
29460 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
29470 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
29480 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
29490 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
294a0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
294b0 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
294c0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
294d0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
294e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
294f0 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
29500 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
29510 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
29520 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29530 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
29540 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
29550 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
29560 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
29570 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29580 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
29590 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
295a0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
295b0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
295c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
295d0 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
295e0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
295f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
29600 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
29610 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
29620 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
29630 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
29640 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
29650 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
29660 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
29670 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
29680 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
29690 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
296a0 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
296b0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
296c0 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
296d0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
296e0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
296f0 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
29700 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
29710 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
29720 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
29730 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
29740 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
29750 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
29760 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29770 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
29780 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
29790 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
297a0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
297b0 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
297c0 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
297d0 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
297e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
297f0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
29800 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
29810 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29820 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
29830 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
29840 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
29850 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
29860 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
29870 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
29880 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
29890 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
298a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
298b0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
298c0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
298d0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
298e0 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
298f0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
29900 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
29910 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
29920 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
29930 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
29940 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
29950 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
29960 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
29970 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
29980 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29990 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
299a0 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
299b0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
299c0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  [[SQLITE_LIMIT_W
299d0 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20  ORKER_THREADS]] 
299e0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
299f0 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
29a00 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  S</dt>.** <dd>Th
29a10 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
29a20 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f   of auxiliary wo
29a30 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61  rker threads tha
29a40 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70  t a single.** [p
29a50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29a60 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64  t] may start.</d
29a70 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
29a80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29a90 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
29aa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29ab0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
29ac0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
29ad0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
29ae0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
29af0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
29b00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29b10 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
29b20 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
29b30 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
29b40 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
29b50 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
29b60 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
29b70 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
29b80 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
29b90 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
29ba0 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
29bb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
29bc0 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
29bd0 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
29be0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
29bf0 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
29c00 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
29c10 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
29c20 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
29c30 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
29c40 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
29c50 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
29c60 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
29c70 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29c80 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
29c90 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
29ca0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29cb0 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20  _WORKER_THREADS 
29cc0 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a            11../*
29cd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
29ce0 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
29cf0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
29d00 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
29d10 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
29d20 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
29d30 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  3.** CONSTRUCTOR
29d40 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
29d50 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
29d60 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
29d70 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
29d80 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
29d90 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
29da0 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
29db0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
29dc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
29dd0 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
29de0 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
29df0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
29e00 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
29e10 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
29e20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
29e30 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
29e40 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
29e50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
29e60 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
29e70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29e80 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
29e90 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
29ea0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
29eb0 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
29ec0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
29ed0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
29ee0 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
29ef0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
29f00 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
29f10 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
29f20 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
29f30 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
29f40 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
29f50 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
29f60 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
29f70 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
29f80 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
29f90 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
29fa0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
29fb0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
29fc0 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
29fd0 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
29fe0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
29ff0 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f   ^If nByte is po
2a000 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  sitive, then it 
2a010 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2a020 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 66   of bytes read f
2a030 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e  rom zSql.  ^If n
2a040 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68  Byte is zero, th
2a050 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a  en no prepared.*
2a060 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67  * statement is g
2a070 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20  enerated..** If 
2a080 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
2a090 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
2a0a0 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
2a0b0 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
2a0c0 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20  n.** there is a 
2a0d0 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63  small performanc
2a0e0 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70  e advantage to p
2a0f0 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
2a100 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
2a110 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
2a120 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2a130 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
2a140 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
2a150 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
2a160 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  tor..**.** ^If p
2a170 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
2a180 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
2a190 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
2a1a0 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
2a1b0 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
2a1c0 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
2a1d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
2a1e0 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
2a1f0 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
2a200 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
2a210 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
2a220 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
2a230 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
2a240 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
2a250 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
2a260 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
2a270 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
2a280 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
2a290 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a2a0 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
2a2b0 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
2a2c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
2a2d0 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
2a2e0 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
2a2f0 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
2a300 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
2a310 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
2a320 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
2a330 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
2a340 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
2a350 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
2a360 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
2a370 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
2a380 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
2a390 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
2a3a0 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
2a3b0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
2a3c0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
2a3d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2a3e0 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
2a3f0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2a400 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
2a410 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
2a420 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
2a430 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
2a440 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
2a450 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
2a460 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
2a470 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
2a480 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2a490 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
2a4a0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
2a4b0 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
2a4c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2a4d0 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
2a4e0 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
2a4f0 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
2a500 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
2a510 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
2a520 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
2a530 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
2a540 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
2a550 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
2a560 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
2a570 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2a580 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
2a590 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2a5a0 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
2a5b0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2a5c0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
2a5d0 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
2a5e0 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
2a5f0 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
2a600 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
2a610 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
2a620 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
2a630 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
2a640 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
2a650 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
2a660 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
2a670 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
2a680 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
2a690 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2a6a0 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
2a6b0 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
2a6c0 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
2a6d0 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
2a6e0 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
2a6f0 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
2a700 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
2a710 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
2a720 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51  . As many as [SQ
2a730 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f  LITE_MAX_SCHEMA_
2a740 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65  RETRY].** retrie
2a750 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66  s will occur bef
2a760 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ore sqlite3_step
2a770 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20  () gives up and 
2a780 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72  returns an error
2a790 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
2a7a0 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
2a7b0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
2a7c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2a7d0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
2a7e0 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
2a7f0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
2a800 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
2a810 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
2a820 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2a830 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
2a840 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2a850 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
2a860 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
2a870 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
2a880 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
2a890 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
2a8a0 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
2a8b0 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
2a8c0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2a8d0 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
2a8e0 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
2a8f0 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
2a900 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
2a910 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
2a920 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
2a930 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
2a940 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
2a950 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
2a960 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
2a970 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
2a980 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
2a990 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
2a9a0 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
2a9b0 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
2a9c0 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
2a9d0 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
2a9e0 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
2a9f0 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
2aa00 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
2aa10 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
2aa20 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
2aa30 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
2aa40 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
2aa50 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
2aa60 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
2aa70 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
2aa80 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
2aa90 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
2aaa0 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
2aab0 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
2aac0 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
2aad0 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
2aae0 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
2aaf0 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
2ab00 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
2ab10 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
2ab20 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
2ab30 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
2ab40 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
2ab50 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
2ab60 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
2ab70 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
2ab80 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
2ab90 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
2aba0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
2abb0 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
2abc0 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
2abd0 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
2abe0 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f  ENABLE_STAT3] co
2abf0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2ac00 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
2ac10 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
2ac20 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
2ac30 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
2ac40 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2ac50 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2ac60 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2ac70 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
2ac80 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2ac90 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
2aca0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2acb0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2acc0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2acd0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2ace0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2acf0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2ad00 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2ad10 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2ad20 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2ad30 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2ad40 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2ad50 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2ad60 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2ad70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
2ad80 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2ad90 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2ada0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2adb0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
2adc0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2add0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
2ade0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2adf0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2ae00 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2ae10 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2ae20 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2ae30 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2ae40 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2ae50 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2ae60 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2ae70 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2ae80 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2ae90 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2aea0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2aeb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2aec0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2aed0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2aee0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2aef0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2af00 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2af10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2af20 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
2af30 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2af40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2af50 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2af60 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2af70 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2af80 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2af90 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2afa0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2afb0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2afc0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2afd0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2afe0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2aff0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2b000 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
2b010 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2b020 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2b030 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2b040 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2b050 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2b060 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2b070 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2b080 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2b090 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2b0a0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2b0b0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2b0c0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2b0d0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2b0e0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2b0f0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2b100 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2b110 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2b120 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2b130 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
2b140 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
2b150 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
2b160 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   SQL.** METHOD: 
2b170 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2b180 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b190 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65  sql(P) interface
2b1a0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2b1b0 65 72 20 74 6f 20 61 20 63 6f 70 79 20 6f 66 20  er to a copy of 
2b1c0 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c  the UTF-8.** SQL
2b1d0 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
2b1e0 65 61 74 65 20 5b 70 72 65 70 61 72 65 64 20 73  eate [prepared s
2b1f0 74 61 74 65 6d 65 6e 74 5d 20 50 20 69 66 20 50  tatement] P if P
2b200 20 77 61 73 0a 2a 2a 20 63 72 65 61 74 65 64 20   was.** created 
2b210 62 79 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  by either [sqlit
2b220 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2b230 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2b240 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2b250 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
2b260 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69 6e  panded_sql(P) in
2b270 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2b280 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55  a pointer to a U
2b290 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63  TF-8.** string c
2b2a0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53 51  ontaining the SQ
2b2b0 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 72  L text of prepar
2b2c0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 77  ed statement P w
2b2d0 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61  ith.** [bound pa
2b2e0 72 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e 64  rameters] expand
2b2f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
2b300 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 72  example, if a pr
2b310 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b320 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e   is created usin
2b330 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78  g the SQL.** tex
2b340 74 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a  t "SELECT $abc,:
2b350 78 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72 61  xyz" and if para
2b360 6d 65 74 65 72 20 24 61 62 63 20 69 73 20 62 6f  meter $abc is bo
2b370 75 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20 32  und to integer 2
2b380 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d  345.** and param
2b390 65 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e 62  eter :xyz is unb
2b3a0 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ound, then sqlit
2b3b0 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 65  e3_sql() will re
2b3c0 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67  turn.** the orig
2b3d0 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 45  inal string, "SE
2b3e0 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20  LECT $abc,:xyz" 
2b3f0 62 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70 61  but sqlite3_expa
2b400 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69  nded_sql().** wi
2b410 6c 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45 43  ll return "SELEC
2b420 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a  T 2345,NULL".)^.
2b430 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2b440 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2b450 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2b460 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75  rns NULL if insu
2b470 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a  fficient memory.
2b480 2a 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  ** is available 
2b490 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
2b4a0 6c 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65  lt, or if the re
2b4b0 73 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 65  sult would excee
2b4c0 64 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78  d the.** the max
2b4d0 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67  imum string leng
2b4e0 74 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  th determined by
2b4f0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d   the [SQLITE_LIM
2b500 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a  IT_LENGTH]..**.*
2b510 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 54  * ^The [SQLITE_T
2b520 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d  RACE_SIZE_LIMIT]
2b530 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2b540 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 20  tion limits the 
2b550 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64  size of.** bound
2b560 20 70 61 72 61 6d 65 74 65 72 20 65 78 70 61 6e   parameter expan
2b570 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51  sions.  ^The [SQ
2b580 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d  LITE_OMIT_TRACE]
2b590 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
2b5a0 20 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20 73   option causes s
2b5b0 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2b5c0 73 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 20  sql() to always 
2b5d0 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a  return NULL..**.
2b5e0 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72  ** ^The string r
2b5f0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2b600 65 33 5f 73 71 6c 28 50 29 20 69 73 20 6d 61 6e  e3_sql(P) is man
2b610 61 67 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  aged by SQLite a
2b620 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74  nd is.** automat
2b630 69 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68 65  ically freed whe
2b640 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  n the prepared s
2b650 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61  tatement is fina
2b660 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  lized..** ^The s
2b670 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62  tring returned b
2b680 79 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  y sqlite3_expand
2b690 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74 68  ed_sql(P), on th
2b6a0 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a 2a  e other hand,.**
2b6b0 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   is obtained fro
2b6c0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2b6d0 63 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 62 65  c()] and must be
2b6e0 20 66 72 65 65 20 62 79 20 74 68 65 20 61 70 70   free by the app
2b6f0 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20 70  lication.** by p
2b700 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
2b710 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
2b720 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2b730 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
2b740 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2b750 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 78  char *sqlite3_ex
2b760 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69 74  panded_sql(sqlit
2b770 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2b780 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b790 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2b7a0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
2b7b0 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
2b7c0 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ase.** METHOD: s
2b7d0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2b7e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2b7f0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
2b800 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2b810 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
2b820 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
2b830 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
2b840 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
2b850 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
2b860 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
2b870 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2b880 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
2b890 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
2b8a0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2b8b0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2b8c0 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
2b8d0 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
2b8e0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2b8f0 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
2b900 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
2b910 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
2b920 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
2b930 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
2b940 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
2b950 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
2b960 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
2b970 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
2b980 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
2b990 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
2b9a0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2b9b0 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
2b9c0 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
2b9d0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
2b9e0 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
2b9f0 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
2ba00 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
2ba10 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
2ba20 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
2ba30 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
2ba40 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2ba50 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
2ba60 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
2ba70 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
2ba80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2ba90 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
2baa0 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
2bab0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
2bac0 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
2bad0 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
2bae0 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
2baf0 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
2bb00 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
2bb10 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
2bb20 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
2bb30 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
2bb40 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
2bb50 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
2bb60 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
2bb70 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
2bb80 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2bb90 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
2bba0 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
2bbb0 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
2bbc0 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
2bbd0 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
2bbe0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
2bbf0 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
2bc00 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
2bc10 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
2bc20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2bc30 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
2bc40 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
2bc50 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
2bc60 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
2bc70 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
2bc80 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
2bc90 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
2bca0 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
2bcb0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
2bcc0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
2bcd0 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
2bce0 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73   disk..** ^The s
2bcf0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2bd00 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63 65  only() interface
2bd10 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 66 6f   returns true fo
2bd20 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65 0a  r [BEGIN] since.
2bd30 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65 6c  ** [BEGIN] merel
2bd40 79 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c 20  y sets internal 
2bd50 66 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20 5b  flags, but the [
2bd60 42 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d 45  BEGIN|BEGIN IMME
2bd70 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42  DIATE] and.** [B
2bd80 45 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c 55  EGIN|BEGIN EXCLU
2bd90 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20 64  SIVE] commands d
2bda0 6f 20 74 6f 75 63 68 20 74 68 65 20 64 61 74 61  o touch the data
2bdb0 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20 73  base and so.** s
2bdc0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2bdd0 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20 66  only() returns f
2bde0 61 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20 63  alse for those c
2bdf0 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20  ommands..*/.int 
2be00 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2be10 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
2be20 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2be30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
2be40 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70  ermine If A Prep
2be50 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48  ared Statement H
2be60 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a  as Been Reset.**
2be70 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2be80 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2be90 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2bea0 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
2beb0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
2bec0 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
2bed0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2bee0 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
2bef0 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
2bf00 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
2bf10 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2bf20 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74  S)] but has neit
2bf30 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c  her run to compl
2bf40 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a  etion (returned.
2bf50 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
2bf60 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
2bf70 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20  tep(S)]) nor.** 
2bf80 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
2bf90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2bfa0 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
2bfb0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
2bfc0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
2bfd0 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
2bfe0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2bff0 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
2c000 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
2c010 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
2c020 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
2c030 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
2c040 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
2c050 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
2c060 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2c070 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
2c080 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
2c090 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
2c0a0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
2c0b0 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
2c0c0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
2c0d0 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
2c0e0 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
2c0f0 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
2c100 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
2c110 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
2c120 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
2c130 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
2c140 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
2c150 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
2c160 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
2c170 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
2c180 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
2c190 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
2c1a0 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
2c1b0 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
2c1c0 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71   open..*/.int sq
2c1d0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2c1e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2c1f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c200 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
2c210 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
2c220 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
2c230 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c240 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
2c250 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c260 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
2c270 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
2c280 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
2c290 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
2c2a0 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
2c2b0 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
2c2c0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
2c2d0 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
2c2e0 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
2c2f0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
2c300 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
2c310 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
2c320 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2c330 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
2c340 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
2c350 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
2c360 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
2c370 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
2c380 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2c390 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
2c3a0 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
2c3b0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
2c3c0 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
2c3d0 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
2c3e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c3f0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
2c400 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
2c410 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
2c420 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
2c430 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2c440 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
2c450 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
2c460 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
2c470 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
2c480 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
2c490 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
2c4a0 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
2c4b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c4c0 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  alue.  The.** [s
2c4d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
2c4e0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61  ()] interface ca
2c4f0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e  n be used to con
2c500 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a  struct a new .**
2c510 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2c520 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e  e3_value from an
2c530 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2c540 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  ite3_value..**.*
2c550 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f  * The terms "pro
2c560 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70  tected" and "unp
2c570 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20  rotected" refer 
2c580 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  to whether or no
2c590 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20  t.** a mutex is 
2c5a0 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e  held.  An intern
2c5b0 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
2c5c0 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
2c5d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2c5e0 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
2c5f0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
2c600 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2c610 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2c620 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
2c630 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
2c640 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
2c650 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
2c660 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
2c670 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b  FE=0] and with [
2c680 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2c690 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
2c6a0 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69  0).** or if SQLi
2c6b0 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65  te is run in one
2c6c0 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65   of reduced mute
2c6d0 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c  x modes .** [SQL
2c6e0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
2c6f0 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c  ETHREAD] or [SQL
2c700 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
2c710 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20  THREAD].** then 
2c720 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
2c730 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
2c740 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
2c750 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2c760 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c770 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
2c780 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  be used intercha
2c790 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65  ngeably.  Howeve
2c7a0 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75  r,.** for maximu
2c7b0 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69  m code portabili
2c7c0 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ty it is recomme
2c7d0 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
2c7e0 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20  ations.** still 
2c7f0 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
2c800 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
2c810 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
2c820 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2c830 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2c840 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74  even when not st
2c850 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e  rictly required.
2c860 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2c870 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2c880 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
2c890 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
2c8a0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
2c8b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
2c8c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2c8d0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2c8e0 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
2c8f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c900 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
2c910 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2c920 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2c930 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
2c940 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
2c950 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c960 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
2c970 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
2c980 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2c990 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ult_value()] and
2c9a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
2c9b0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  alue()]..** The 
2c9c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2c9d0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
2c9e0 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
2c9f0 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
2ca00 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
2ca10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2ca20 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
2ca30 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
2ca40 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
2ca50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ca60 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  F: SQL Function 
2ca70 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a  Context Object.*
2ca80 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
2ca90 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
2caa0 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
2cab0 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
2cac0 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
2cad0 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e  ntext object.  ^
2cae0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
2caf0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2cb00 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
2cb10 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
2cb20 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
2cb30 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2cb40 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
2cb50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2cb60 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2cb70 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2cb80 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
2cb90 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
2cba0 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
2cbb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
2cbc0 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
2cbd0 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
2cbe0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2cbf0 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
2cc00 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2cc10 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2cc20 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
2cc30 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
2cc40 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
2cc50 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
2cc60 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
2cc70 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
2cc80 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
2cc90 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
2cca0 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
2ccb0 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
2ccc0 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
2ccd0 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  d Statements.** 
2cce0 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20  KEYWORDS: {host 
2ccf0 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74  parameter} {host
2cd00 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f   parameters} {ho
2cd10 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
2cd20 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e}.** KEYWORDS: 
2cd30 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20  {SQL parameter} 
2cd40 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d  {SQL parameters}
2cd50 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   {parameter bind
2cd60 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ing}.** METHOD: 
2cd70 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2cd80 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20  ** ^(In the SQL 
2cd90 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
2cda0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
2cdb0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2cdc0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
2cdd0 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79  .** literals may
2cde0 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20   be replaced by 
2cdf0 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68  a [parameter] th
2ce00 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f  at matches one o
2ce10 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74  f following.** t
2ce20 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20  emplates:.**.** 
2ce30 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
2ce40 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
2ce50 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c   <li>  :VVV.** <
2ce60 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69  li>  @VVV.** <li
2ce70 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
2ce80 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65  .**.** In the te
2ce90 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e  mplates above, N
2cea0 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  NN represents an
2ceb0 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
2cec0 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70  ,.** and VVV rep
2ced0 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61  resents an alpha
2cee0 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69  numeric identifi
2cef0 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75  er.)^  ^The valu
2cf00 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70  es of these.** p
2cf10 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
2cf20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
2cf30 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72  ameter names" or
2cf40 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
2cf50 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
2cf60 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
2cf70 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2cf80 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
2cf90 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
2cfa0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2cfb0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2cfc0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
2cfd0 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
2cfe0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
2cff0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
2d000 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
2d010 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2d020 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
2d030 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
2d040 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
2d050 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2d060 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  ex of the SQL pa
2d070 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
2d080 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d  t..** ^The leftm
2d090 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
2d0a0 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
2d0b0 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20  f 1.  ^When the 
2d0c0 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
2d0d0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
2d0e0 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
2d0f0 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
2d100 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
2d110 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
2d120 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
2d130 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
2d140 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e  ence..** ^The in
2d150 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
2d160 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
2d170 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
2d180 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
2d190 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2d1a0 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
2d1b0 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e  esired.  ^The in
2d1c0 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
2d1d0 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
2d1e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
2d1f0 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61  ..** ^The NNN va
2d200 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
2d210 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73  een 1 and the [s
2d220 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
2d230 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51  ** parameter [SQ
2d240 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
2d250 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66  BLE_NUMBER] (def
2d260 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
2d270 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
2d280 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
2d290 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
2d2a0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
2d2b0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
2d2c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
2d2d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2d2e0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2d2f0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
2d300 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2d310 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c  _blob() is a NUL
2d320 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
2d330 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2d340 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65  ter.** is ignore
2d350 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65  d and the end re
2d360 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65  sult is the same
2d370 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   as sqlite3_bind
2d380 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  _null()..**.** ^
2d390 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e  (In those routin
2d3a0 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66  es that have a f
2d3b0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
2d3c0 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65  its value is the
2d3d0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
2d3e0 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d  tes in the param
2d3f0 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65  eter.  To be cle
2d400 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73  ar: the value is
2d410 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2d420 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69  f <u>bytes</u> i
2d430 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74  n the value, not
2d440 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2d450 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20  haracters.)^.** 
2d460 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
2d470 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2d480 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
2d490 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2d4a0 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e  text16().** is n
2d4b0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
2d4c0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
2d4d0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
2d4e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2d4f0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
2d500 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2d510 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72  ..** If the four
2d520 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2d530 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2d540 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c  b() is negative,
2d550 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68   then.** the beh
2d560 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2d570 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d  ed..** If a non-
2d580 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20  negative fourth 
2d590 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f  parameter is pro
2d5a0 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33  vided to sqlite3
2d5b0 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20  _bind_text().** 
2d5c0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2d5d0 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69  text16() or sqli
2d5e0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2d5f0 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70  ) then.** that p
2d600 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
2d610 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74   the byte offset
2d620 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55  .** where the NU
2d630 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
2d640 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e  ld occur assumin
2d650 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72  g the string wer
2d660 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61  e NUL.** termina
2d670 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
2d680 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
2d690 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74  r at byte offset
2d6a0 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20  s less than .** 
2d6b0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2d6c0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2d6d0 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  r then the resul
2d6e0 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75  ting string valu
2d6f0 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69  e will.** contai
2d700 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e  n embedded NULs.
2d710 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20    The result of 
2d720 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f  expressions invo
2d730 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a  lving strings.**
2d740 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
2d750 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
2d760 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
2d770 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
2d780 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69  he BLOB and stri
2d790 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72  ng binding inter
2d7a0 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65  faces.** is a de
2d7b0 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
2d7c0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
2d7d0 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
2d7e0 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
2d7f0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
2d800 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72   it.  ^The destr
2d810 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a  uctor is called.
2d820 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ** to dispose of
2d830 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
2d840 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
2d850 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49  call to bind API
2d860 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74   fails..** ^If t
2d870 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2d880 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
2d890 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
2d8a0 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
2d8b0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
2d8c0 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
2d8d0 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
2d8e0 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
2d8f0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
2d900 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
2d910 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ed..** ^If the f
2d920 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
2d930 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
2d940 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
2d950 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
2d960 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
2d970 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
2d980 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
2d990 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
2d9a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2d9b0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2d9c0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  s..**.** ^The si
2d9d0 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  xth argument to 
2d9e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2d9f0 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e  t64() must be on
2da00 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  e of.** [SQLITE_
2da10 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
2da20 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  TF16], [SQLITE_U
2da30 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16BE], or [SQL
2da40 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20  ITE_UTF16LE].** 
2da50 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65  to specify the e
2da60 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74  ncoding of the t
2da70 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64  ext in the third
2da80 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a   parameter.  If.
2da90 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67  ** the sixth arg
2daa0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2dab0 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69  _bind_text64() i
2dac0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
2dad0 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75  .** allowed valu
2dae0 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20  es shown above, 
2daf0 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65  or if the text e
2db00 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
2db10 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  rent.** from the
2db20 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66   encoding specif
2db30 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68  ied by the sixth
2db40 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
2db50 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
2db60 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2db70 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2db80 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
2db90 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
2dba0 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
2dbb0 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
2dbc0 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73  lled with zeroes
2dbd0 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75  .  ^A zeroblob u
2dbe0 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
2dbf0 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
2dc00 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
2dc10 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a   to hold its siz
2dc20 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
2dc30 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
2dc40 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
2dc50 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
2dc60 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65  ve as placeholde
2dc70 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
2dc80 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
2dc90 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
2dca0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2dcb0 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
2dcc0 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
2dcd0 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  O] routines..** 
2dce0 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75  ^A negative valu
2dcf0 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
2dd00 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
2dd10 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
2dd20 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  ..**.** ^If any 
2dd30 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  of the sqlite3_b
2dd40 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2dd50 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68   are called with
2dd60 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
2dd70 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  ** for the [prep
2dd80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2dd90 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72  or with a prepar
2dda0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  ed statement for
2ddb0 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
2ddc0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62  e3_step()] has b
2ddd0 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20  een called more 
2dde0 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73  recently than [s
2ddf0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
2de00 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c  .** then the cal
2de10 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  l will return [S
2de20 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2de30 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62  If any sqlite3_b
2de40 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ind_().** routin
2de50 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70  e is passed a [p
2de60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2de70 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e  t] that has been
2de80 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a   finalized, the.
2de90 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  ** result is und
2dea0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2deb0 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
2dec0 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65  ** ^Bindings are
2ded0 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
2dee0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
2def0 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
2df00 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  * ^Unbound param
2df10 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
2df20 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
2df30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2df40 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65  3_bind_* routine
2df50 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
2df60 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
2df70 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  or an.** [error 
2df80 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e  code] if anythin
2df90 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
2dfa0 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47   ^[SQLITE_TOOBIG
2dfb0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2dfc0 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20  ned if the size 
2dfd0 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  of a string or B
2dfe0 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c  LOB.** exceeds l
2dff0 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79  imits imposed by
2e000 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
2e010 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  ([SQLITE_LIMIT_L
2e020 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53  ENGTH]) or.** [S
2e030 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48  QLITE_MAX_LENGTH
2e040 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  ]..** ^[SQLITE_R
2e050 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
2e060 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
2e070 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
2e080 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
2e090 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
2e0a0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
2e0b0 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
2e0c0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2e0d0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2e0e0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
2e0f0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2e100 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2e110 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
2e120 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2e130 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
2e140 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2e150 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2e160 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2e170 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
2e180 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2e190 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2e1a0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2e1b0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2e1c0 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  d*, sqlite3_uint
2e1d0 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
2e1e0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
2e1f0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2e200 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
2e210 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2e220 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
2e230 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2e240 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
2e250 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
2e260 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2e270 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
2e280 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
2e290 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
2e2a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
2e2b0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
2e2c0 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
2e2d0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
2e2e0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63  ite3_stmt*,int,c
2e2f0 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76  onst char*,int,v
2e300 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2e310 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2e320 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2e330 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2e340 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
2e350 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2e360 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2e370 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73  text64(sqlite3_s
2e380 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2e390 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
2e3a0 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
2e3b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e3c0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c   void(*)(void*),
2e3d0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65   unsigned char e
2e3e0 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71  ncoding);.int sq
2e3f0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2e400 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e410 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
2e420 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2e430 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2e440 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
2e450 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
2e460 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2e470 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71  nd_zeroblob64(sq
2e480 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e490 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
2e4a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e4b0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
2e4c0 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  L Parameters.** 
2e4d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2e4e0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  stmt.**.** ^This
2e4f0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2e500 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
2e510 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
2e520 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
2e530 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2e540 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
2e550 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
2e560 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
2e570 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
2e580 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
2e590 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
2e5a0 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
2e5b0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
2e5c0 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
2e5d0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2e5e0 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
2e5f0 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
2e600 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
2e610 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
2e620 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
2e630 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
2e640 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
2e650 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
2e660 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
2e670 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
2e680 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
2e690 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
2e6a0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
2e6b0 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
2e6c0 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
2e6d0 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
2e6e0 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
2e6f0 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
2e700 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
2e710 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2e720 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2e730 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2e740 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2e750 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2e760 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2e770 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2e780 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2e790 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2e7a0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2e7b0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
2e7c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e7d0 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
2e7e0 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d  t Parameter.** M
2e7f0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2e800 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
2e810 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2e820 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
2e830 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2e840 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
2e850 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
2e860 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
2e870 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e880 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
2e890 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
2e8a0 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
2e8b0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
2e8c0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
2e8d0 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
2e8e0 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
2e8f0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
2e900 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
2e910 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
2e920 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
2e930 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
2e940 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
2e950 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
2e960 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
2e970 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
2e980 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
2e990 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
2e9a0 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
2e9b0 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
2e9c0 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
2e9d0 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
2e9e0 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
2e9f0 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
2ea00 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
2ea10 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
2ea20 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
2ea30 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
2ea40 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
2ea50 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
2ea60 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
2ea70 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
2ea80 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
2ea90 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
2eaa0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
2eab0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2eac0 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
2ead0 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
2eae0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
2eaf0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
2eb00 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
2eb10 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
2eb20 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
2eb30 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
2eb40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2eb50 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
2eb60 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2eb70 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2eb80 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2eb90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2eba0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2ebb0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
2ebc0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2ebd0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2ebe0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2ebf0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2ec00 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
2ec10 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
2ec20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ec30 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
2ec40 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
2ec50 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44  n Name.** METHOD
2ec60 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2ec70 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
2ec80 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
2ec90 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
2eca0 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
2ecb0 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
2ecc0 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
2ecd0 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
2ece0 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
2ecf0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2ed00 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2ed10 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
2ed20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
2ed30 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
2ed40 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
2ed50 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
2ed60 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
2ed70 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
2ed80 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
2ed90 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
2eda0 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
2edb0 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
2edc0 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
2edd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2ede0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
2edf0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2ee00 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2ee10 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2ee20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2ee30 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2ee40 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2ee50 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2ee60 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  _name()]..*/.int
2ee70 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2ee80 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
2ee90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
2eea0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
2eeb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2eec0 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
2eed0 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
2eee0 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed Statement.** 
2eef0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2ef00 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74  stmt.**.** ^Cont
2ef10 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
2ef20 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
2ef30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2ef40 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a   does not reset.
2ef50 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
2ef60 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
2ef70 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70  ings] on a [prep
2ef80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2ef90 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f  .** ^Use this ro
2efa0 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61  utine to reset a
2efb0 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
2efc0 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  rs to NULL..*/.i
2efd0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
2efe0 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
2eff0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2f000 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2f010 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
2f020 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20  A Result Set.** 
2f030 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2f040 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  stmt.**.** ^Retu
2f050 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
2f060 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2f070 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
2f080 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
2f090 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f0a0 74 5d 2e 20 5e 49 66 20 74 68 69 73 20 72 6f 75  t]. ^If this rou
2f0b0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 2c 20  tine returns 0, 
2f0c0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 0a  that means the .
2f0d0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2f0e0 74 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 20  tement] returns 
2f0f0 6e 6f 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  no data (for exa
2f100 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
2f110 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20  )..** ^However, 
2f120 6a 75 73 74 20 62 65 63 61 75 73 65 20 74 68 69  just because thi
2f130 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
2f140 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d  s a positive num
2f150 62 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ber does not.** 
2f160 6d 65 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72  mean that one or
2f170 20 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 61   more rows of da
2f180 74 61 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72  ta will be retur
2f190 6e 65 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 20  ned.  ^A SELECT 
2f1a0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c  statement.** wil
2f1b0 6c 20 61 6c 77 61 79 73 20 68 61 76 65 20 61 20  l always have a 
2f1c0 70 6f 73 69 74 69 76 65 20 73 71 6c 69 74 65 33  positive sqlite3
2f1d0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20  _column_count() 
2f1e0 62 75 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  but depending on
2f1f0 20 74 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c   the.** WHERE cl
2f200 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
2f210 20 61 6e 64 20 74 68 65 20 74 61 62 6c 65 20 63   and the table c
2f220 6f 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 74  ontent, it might
2f230 20 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e   return no rows.
2f240 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2f250 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
2f260 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
2f270 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2f280 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2f290 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2f2a0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
2f2b0 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
2f2c0 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult Set.** METHO
2f2d0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2f2e0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2f2f0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2f300 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
2f310 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
2f320 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
2f330 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
2f340 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2f350 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  nt.  ^The sqlite
2f360 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
2f370 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
2f380 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2f390 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2f3a0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
2f3b0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
2f3c0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
2f3d0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2f3e0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
2f3f0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
2f400 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66   string.  ^The f
2f410 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2f420 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
2f430 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
2f440 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
2f450 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
2f460 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e  ment. ^The secon
2f470 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
2f480 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
2f490 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d  ber.  ^The leftm
2f4a0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75  ost column is nu
2f4b0 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mber 0..**.** ^T
2f4c0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2f4d0 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
2f4e0 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
2f4f0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2f500 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
2f510 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
2f520 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2f530 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
2f540 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
2f550 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
2f560 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
2f570 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
2f580 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
2f590 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
2f5a0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
2f5b0 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
2f5c0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2f5d0 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
2f5e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2f5f0 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
2f600 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
2f610 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
2f620 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
2f630 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
2f640 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
2f650 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
2f660 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
2f670 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
2f680 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
2f690 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
2f6a0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
2f6b0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
2f6c0 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
2f6d0 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
2f6e0 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
2f6f0 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
2f700 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
2f710 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
2f720 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
2f730 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
2f740 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
2f750 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
2f760 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
2f770 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
2f780 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
2f790 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
2f7a0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2f7b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2f7c0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2f7d0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73  t*, int N);.cons
2f7e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2f7f0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
2f800 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f810 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
2f820 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
2f830 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
2f840 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44  Result.** METHOD
2f850 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2f860 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2f870 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
2f880 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
2f890 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
2f8a0 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
2f8b0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
2f8c0 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
2f8d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
2f8e0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
2f8f0 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
2f900 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
2f910 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
2f920 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
2f930 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
2f940 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
2f950 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
2f960 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
2f970 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
2f980 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
2f990 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
2f9a0 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
2f9b0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2f9c0 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
2f9d0 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
2f9e0 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
2f9f0 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
2fa00 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
2fa10 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
2fa20 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
2fa30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2fa40 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
2fa50 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
2fa60 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2fa70 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
2fa80 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
2fa90 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
2faa0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
2fab0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2fac0 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
2fad0 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
2fae0 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
2faf0 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
2fb00 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
2fb10 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
2fb20 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
2fb30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
2fb40 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
2fb50 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
2fb60 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
2fb70 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
2fb80 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
2fb90 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
2fba0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2fbb0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
2fbc0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2fbd0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2fbe0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2fbf0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2fc00 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
2fc10 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
2fc20 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
2fc30 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
2fc40 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
2fc50 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
2fc60 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
2fc70 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
2fc80 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
2fc90 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
2fca0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
2fcb0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2fcc0 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
2fcd0 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
2fce0 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
2fcf0 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
2fd00 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
2fd10 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
2fd20 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
2fd30 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
2fd40 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
2fd50 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
2fd60 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
2fd70 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
2fd80 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
2fd90 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
2fda0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2fdb0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2fdc0 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
2fdd0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
2fde0 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
2fdf0 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
2fe00 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
2fe10 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
2fe20 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
2fe30 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
2fe40 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
2fe50 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
2fe60 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
2fe70 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
2fe80 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
2fe90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
2fea0 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
2feb0 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
2fec0 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
2fed0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
2fee0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
2fef0 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
2ff00 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
2ff10 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
2ff20 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2ff30 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2ff40 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
2ff50 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
2ff60 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
2ff70 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
2ff80 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
2ff90 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2ffa0 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
2ffb0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2ffc0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2ffd0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2ffe0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
2fff0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
30000 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
30010 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
30020 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
30030 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
30040 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
30050 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
30060 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
30070 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
30080 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
30090 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
300a0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
300b0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
300c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
300d0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
300e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
300f0 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
30100 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
30110 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
30120 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
30130 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
30140 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
30150 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
30160 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
30170 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
30180 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
30190 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
301a0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
301b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
301c0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
301d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
301e0 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
301f0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
30200 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30210 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
30220 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
30230 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  esult.** METHOD:
30240 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30250 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20  .** ^(The first 
30260 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
30270 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30280 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  nt]..** If this 
30290 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
302a0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
302b0 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
302c0 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72  lumn of the.** r
302d0 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
302e0 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45  et of that [SELE
302f0 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63  CT] is a table c
30300 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a  olumn (not an.**
30310 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
30320 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68  ubquery) then th
30330 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
30340 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
30350 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
30360 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e  ed.)^  ^If the N
30370 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
30380 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
30390 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
303a0 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
303b0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
303c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
303d0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
303e0 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
303f0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a  UTF-8 encoded..*
30400 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
30410 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61  le, given the da
30420 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
30430 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
30440 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
30450 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ;.**.** and the 
30460 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
30470 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
30480 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
30490 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
304a0 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20   t1;.**.** this 
304b0 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
304c0 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
304d0 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
304e0 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a  e second result.
304f0 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  ** column (i==1)
30500 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
30510 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
30520 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
30530 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a   (i==0).)^.**.**
30540 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79   ^SQLite uses dy
30550 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
30560 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74  yping.  ^So just
30570 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
30580 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
30590 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
305a0 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
305b0 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
305c0 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
305d0 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
305e0 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
305f0 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
30600 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
30610 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
30620 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
30630 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
30640 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73   ^Type.** is ass
30650 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64  ociated with ind
30660 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20  ividual values, 
30670 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e  not with the con
30680 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20  tainers.** used 
30690 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61  to hold those va
306a0 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  lues..*/.const c
306b0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
306c0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
306d0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
306e0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
306f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
30700 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
30710 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
30720 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
30730 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
30740 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ement.** METHOD:
30750 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30760 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
30770 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30780 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
30790 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
307a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
307b0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
307c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
307d0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
307e0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
307f0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
30800 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
30810 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
30820 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
30830 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
30840 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
30850 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
30860 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
30870 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
30880 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
30890 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
308a0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
308b0 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
308c0 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
308d0 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
308e0 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
308f0 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
30900 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
30910 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
30920 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
30930 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
30940 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
30950 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
30960 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
30970 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
30980 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
30990 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
309a0 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
309b0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
309c0 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
309d0 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
309e0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
309f0 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
30a00 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
30a10 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c  .**.** ^In the l
30a20 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
30a30 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
30a40 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
30a50 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
30a60 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
30a70 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
30a80 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
30a90 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
30aa0 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  E]..** ^With the
30ab0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
30ac0 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
30ad0 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
30ae0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
30af0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
30b00 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
30b10 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
30b20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d  ^[SQLITE_BUSY] m
30b30 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
30b40 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
30b50 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
30b60 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
30b70 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
30b80 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
30b90 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  .  ^If the state
30ba0 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
30bb0 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
30bc0 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
30bd0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
30be0 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
30bf0 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
30c00 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
30c10 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
30c20 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
30c30 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
30c40 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
30c50 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
30c60 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
30c70 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
30c80 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
30c90 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  tinuing..**.** ^
30ca0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
30cb0 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
30cc0 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
30cd0 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
30ce0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
30cf0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
30d00 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
30d10 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
30d20 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
30d30 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
30d40 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
30d50 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
30d60 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
30d70 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
30d80 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
30d90 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49   state..**.** ^I
30da0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
30db0 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
30dc0 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
30dd0 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
30de0 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
30df0 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
30e00 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
30e10 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
30e20 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
30e30 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
30e40 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
30e50 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
30e60 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
30e70 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
30e80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
30e90 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
30ea0 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
30eb0 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
30ec0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45  **.** ^[SQLITE_E
30ed0 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
30ee0 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
30ef0 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
30f00 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
30f10 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
30f20 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
30f30 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
30f40 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
30f50 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
30f60 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
30f70 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
30f80 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
30f90 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69  rrmsg()]..** ^Wi
30fa0 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
30fb0 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
30fc0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
30fd0 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
30fe0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
30ff0 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
31000 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
31010 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
31020 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
31030 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
31040 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
31050 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
31060 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
31070 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74  atement].  ^In t
31080 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
31090 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
310a0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
310b0 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
310c0 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
310d0 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
310e0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
310f0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
31100 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
31110 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
31120 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
31130 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
31140 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
31150 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
31160 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
31170 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
31180 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
31190 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
311a0 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
311b0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
311c0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
311d0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
311e0 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
311f0 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
31200 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
31210 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
31220 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
31230 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
31240 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
31250 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
31260 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76  .**.** For all v
31270 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
31280 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c  e up to and incl
31290 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20  uding 3.6.23.1, 
312a0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
312b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
312c0 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65  as required afte
312d0 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  r sqlite3_step()
312e0 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69   returned anythi
312f0 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  ng.** other than
31300 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65   [SQLITE_ROW] be
31310 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
31320 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
31330 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
31340 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
31350 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
31360 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
31370 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
31380 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20  _reset()] would 
31390 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51  result in an [SQ
313a0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74  LITE_MISUSE] ret
313b0 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  urn from.** sqli
313c0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74  te3_step().  But
313d0 20 61 66 74 65 72 20 5b 76 65 72 73 69 6f 6e 20   after [version 
313e0 33 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74 65  3.6.23.1] ([date
313f0 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a  of:3.6.23.1],.**
31400 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
31410 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67  began.** calling
31420 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31430 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  )] automatically
31440 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73   in this circums
31450 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20  tance rather.** 
31460 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
31470 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
31480 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e   This is not con
31490 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74  sidered a compat
314a0 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b  ibility.** break
314b0 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70   because any app
314c0 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76  lication that ev
314d0 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53  er receives an S
314e0 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72  QLITE_MISUSE err
314f0 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20  or.** is broken 
31500 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  by definition.  
31510 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
31520 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70  _AUTORESET] comp
31530 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a  ile-time option.
31540 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
31550 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65  o restore the le
31560 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a  gacy behavior..*
31570 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
31580 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
31590 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
315a0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
315b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
315c0 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
315d0 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
315e0 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
315f0 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
31600 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
31610 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
31620 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
31630 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
31640 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
31650 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
31660 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
31670 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
31680 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
31690 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
316a0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
316b0 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
316c0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
316d0 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
316e0 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
316f0 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
31700 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
31710 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
31720 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
31730 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
31740 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
31750 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
31760 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
31770 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
31780 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
31790 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
317a0 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
317b0 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
317c0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
317d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
317e0 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
317f0 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
31800 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
31810 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
31820 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
31830 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
31840 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
31850 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
31860 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
31870 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  mended..*/.int s
31880 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
31890 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
318a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
318b0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
318c0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  n a result set.*
318d0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
318e0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
318f0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
31900 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63  ount(P) interfac
31910 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
31920 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
31930 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  in the.** curren
31940 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
31950 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
31960 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31970 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72  P..** ^If prepar
31980 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64  ed statement P d
31990 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73  oes not have res
319a0 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65  ults ready to re
319b0 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c  turn.** (via cal
319c0 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ls to the [sqlit
319d0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
319e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
319f0 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ()] of.** interf
31a00 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74  aces) then sqlit
31a10 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
31a20 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e   returns 0..** ^
31a30 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
31a40 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
31a50 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30  e also returns 0
31a60 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20   if P is a NULL 
31a70 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65  pointer..** ^The
31a80 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
31a90 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72  unt(P) routine r
31aa0 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20  eturns 0 if the 
31ab0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
31ac0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
31ad0 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b  p](P) returned [
31ae0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e  SQLITE_DONE].  ^
31af0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
31b00 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c  _count(P).** wil
31b10 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72  l return non-zer
31b20 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61  o if previous ca
31b30 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
31b40 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
31b50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  .** [SQLITE_ROW]
31b60 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20  , except in the 
31b70 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41  case of the [PRA
31b80 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f  GMA incremental_
31b90 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65  vacuum].** where
31ba0 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
31bb0 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61  ns zero since ea
31bc0 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20  ch step of that 
31bd0 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72  multi-step.** pr
31be0 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63  agma returns 0 c
31bf0 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a  olumns of data..
31c00 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
31c10 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
31c20 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
31c30 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
31c40 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
31c50 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
31c60 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
31c70 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
31c80 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
31c90 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e  ITE_TEXT.**.** ^
31ca0 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  (Every value in 
31cb0 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
31cc0 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
31cd0 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
31ce0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
31cf0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
31d00 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
31d10 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
31d20 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
31d30 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
31d40 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
31d50 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
31d60 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  l>)^.**.** These
31d70 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
31d80 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
31d90 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
31da0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
31db0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
31dc0 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
31dd0 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
31de0 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
31df0 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
31e00 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
31e10 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
31e20 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
31e30 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
31e40 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
31e50 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
31e60 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
31e70 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
31e80 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
31e90 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
31ea0 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
31eb0 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
31ec0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
31ed0 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
31ee0 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
31ef0 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
31f00 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
31f10 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
31f20 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
31f30 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
31f40 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
31f50 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
31f60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
31f70 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
31f80 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57   A Query.** KEYW
31f90 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
31fa0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
31fb0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
31fc0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
31fd0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
31fe0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
31ff0 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20   about a single 
32000 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75  column of the cu
32010 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20  rrent.** result 
32020 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
32030 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20   ^In every case 
32040 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
32050 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a  nt is a pointer.
32060 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  ** to the [prepa
32070 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
32080 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61  hat is being eva
32090 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c  luated (the [sql
320a0 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74  ite3_stmt*].** t
320b0 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
320c0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70   from [sqlite3_p
320d0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
320e0 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
320f0 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  nts).** and the 
32100 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
32110 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
32120 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
32130 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
32140 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
32150 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66  turned. ^The lef
32160 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  tmost column of 
32170 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68  the result set h
32180 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a  as the index 0..
32190 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  ** ^The number o
321a0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
321b0 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64   result can be d
321c0 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a  etermined using.
321d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
321e0 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a  mn_count()]..**.
321f0 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
32200 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
32210 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
32220 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
32230 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f   or if the.** co
32240 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75  lumn index is ou
32250 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20  t of range, the 
32260 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
32270 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ned..** These ro
32280 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20  utines may only 
32290 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  be called when t
322a0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
322b0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
322c0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
322d0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
322e0 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72  ROW] and neither
322f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
32300 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74  et()] nor [sqlit
32310 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68  e3_finalize()] h
32320 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
32330 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a  subsequently..**
32340 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65   If any of these
32350 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
32360 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
32370 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
32380 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
32390 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
323a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
323b0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a  ] has returned.*
323c0 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  * something othe
323d0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
323e0 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73  OW], the results
323f0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
32400 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73  ** If [sqlite3_s
32410 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
32420 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
32430 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
32440 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65  ()].** are calle
32450 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65  d from a differe
32460 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20  nt thread while 
32470 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
32480 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e  tines.** are pen
32490 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ding, then the r
324a0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
324b0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
324c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
324d0 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
324e0 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53  eturns the.** [S
324f0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
32500 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
32510 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
32520 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
32530 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
32540 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
32550 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
32560 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
32570 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
32580 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
32590 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
325a0 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
325b0 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  ULL].  The value
325c0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
325d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
325e0 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
325f0 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74  aningful if no t
32600 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  ype.** conversio
32610 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
32620 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65   as described be
32630 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79  low.  After a ty
32640 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a  pe conversion,.*
32650 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  * the value retu
32660 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
32670 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
32680 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74   undefined.  Fut
32690 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
326a0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
326b0 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
326c0 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
326d0 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
326e0 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
326f0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
32700 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
32710 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
32720 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
32730 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
32740 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75  n_bytes().** rou
32750 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
32760 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
32770 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
32780 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
32790 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
327a0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
327b0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
327c0 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
327d0 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
327e0 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
327f0 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
32800 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
32810 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
32820 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
32830 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
32840 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
32850 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
32860 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
32870 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
32880 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
32890 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
328a0 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
328b0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
328c0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
328d0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
328e0 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
328f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
32900 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
32910 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
32920 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
32930 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74   UTF-16 string t
32940 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
32950 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
32960 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
32970 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
32980 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
32990 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
329a0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
329b0 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  t is a UTF-8 str
329c0 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
329d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
329e0 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
329f0 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
32a00 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74  -16 and then ret
32a10 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
32a20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
32a30 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
32a40 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
32a50 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
32a60 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65  mn_bytes16() use
32a70 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
32a80 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
32a90 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
32aa0 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  to a UTF-16 stri
32ab0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
32ac0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
32ad0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
32ae0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
32af0 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
32b00 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
32b10 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
32b20 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
32b30 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  ** ^The values r
32b40 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
32b50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32b60 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  ()] and .** [sql
32b70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32b80 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e  s16()] do not in
32b90 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
32ba0 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68  erminators at th
32bb0 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
32bc0 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
32bd0 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
32be0 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
32bf0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
32c00 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73  _bytes()] and [s
32c10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32c20 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65  tes16()] are the
32c30 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
32c40 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
32c50 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
32c60 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
32c70 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
32c80 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
32c90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
32ca0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
32cb0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
32cc0 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
32cd0 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
32ce0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
32cf0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
32d00 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
32d10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
32d20 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
32d30 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e  ngth BLOB is a N
32d40 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
32d50 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f  ** <b>Warning:</
32d60 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72  b> ^The object r
32d70 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
32d80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
32d90 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
32da0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
32db0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
32dc0 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65    In a multithre
32dd0 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  aded environment
32de0 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63  ,.** an unprotec
32df0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
32e00 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c  e object may onl
32e10 79 20 62 65 20 75 73 65 64 20 73 61 66 65 6c 79  y be used safely
32e20 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
32e30 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20  3_bind_value()] 
32e40 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
32e50 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ult_value()]..**
32e60 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   If the [unprote
32e70 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
32e80 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  ue] object retur
32e90 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
32ea0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
32eb0 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e  )] is used in an
32ec0 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63  y other way, inc
32ed0 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20  luding calls.** 
32ee0 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
32ef0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
32f00 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  int()], [sqlite3
32f10 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
32f20 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
32f30 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74  alue_bytes()], t
32f40 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e  he behavior is n
32f50 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a  ot threadsafe..*
32f60 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
32f70 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63  nes attempt to c
32f80 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
32f90 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61   where appropria
32fa0 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61  te.  ^For.** exa
32fb0 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
32fc0 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
32fd0 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
32fe0 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
32ff0 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
33000 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
33010 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
33020 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66  ternally to perf
33030 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65  orm the.** conve
33040 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61  rsion automatica
33050 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c  lly.  ^(The foll
33060 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
33070 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
33080 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ons.** that are 
33090 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
330a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
330b0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
330c0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
330d0 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
330e0 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
330f0 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
33100 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
33110 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
33120 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
33130 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
33140 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
33150 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
33160 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
33170 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
33180 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
33190 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
331a0 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
331b0 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
331c0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
331d0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
331e0 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c   Result is a NUL
331f0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
33200 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
33210 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
33220 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
33230 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
33240 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
33250 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
33260 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
33270 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
33280 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
33290 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
332a0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
332b0 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
332c0 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
332d0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
332e0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
332f0 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
33300 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
33310 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
33320 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
33330 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
33340 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
33350 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
33360 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
33370 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42  > [CAST] to BLOB
33380 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
33390 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
333a0 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
333b0 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
333c0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
333d0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
333e0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
333f0 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
33400 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20   TEXT    <td>   
33410 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20  BLOB    <td> No 
33420 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74  change.** <tr><t
33430 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
33440 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
33450 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
33460 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  R.** <tr><td>  B
33470 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
33480 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  AT    <td> [CAST
33490 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72  ] to REAL.** <tr
334a0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
334b0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
334c0 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
334d0 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
334e0 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
334f0 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
33500 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ^.**.** Note tha
33510 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76  t when type conv
33520 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70  ersions occur, p
33530 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
33540 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c   by prior.** cal
33550 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
33560 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  lumn_blob(), sql
33570 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
33580 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  (), and/or.** sq
33590 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
335a0 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76  t16() may be inv
335b0 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70  alidated..** Typ
335c0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
335d0 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
335e0 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
335f0 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
33600 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
33610 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
33620 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
33630 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
33640 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
33650 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
33660 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
33670 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
33680 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
33690 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
336a0 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f  .**      need to
336b0 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
336c0 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a   string.</li>.**
336d0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
336e0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
336f0 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
33700 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
33710 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
33720 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33730 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
33740 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
33750 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
33760 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
33770 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  -16.</li>.** <li
33780 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
33790 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
337a0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
337b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
337c0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
337d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
337e0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
337f0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
33800 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
33810 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69     to UTF-8.</li
33820 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
33830 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65   ^Conversions be
33840 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
33850 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
33860 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
33870 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
33880 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
33890 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
338a0 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
338b0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
338c0 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
338d0 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
338e0 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77  ter references w
338f0 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
33900 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
33910 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
33920 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
33930 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
33940 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
33950 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
33960 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
33970 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
33980 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
33990 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
339a0 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
339b0 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69   safest policy i
339c0 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
339d0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
339e0 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
339f0 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
33a00 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
33a10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33a20 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
33a30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33a40 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
33a50 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
33a60 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
33a70 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
33a80 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
33a90 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
33aa0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
33ab0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
33ac0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
33ad0 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
33ae0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
33af0 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
33b00 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
33b10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
33b20 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
33b30 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
33b40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33b50 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
33b60 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
33b70 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
33b80 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
33b90 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
33ba0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
33bb0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
33bc0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
33bd0 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
33be0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
33bf0 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
33c00 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
33c10 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
33c20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33c30 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
33c40 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
33c50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
33c60 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
33c70 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
33c80 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
33c90 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
33ca0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
33cb0 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
33cc0 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72   ^The pointers r
33cd0 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
33ce0 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
33cf0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
33d00 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
33d10 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
33d20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
33d30 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
33d40 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
33d50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
33d60 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54  ] is called.  ^T
33d70 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
33d80 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
33d90 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
33da0 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
33db0 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65  atically.  Do <e
33dc0 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20  m>not</em> pass 
33dd0 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
33de0 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
33df0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
33e00 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
33e10 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
33e20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  etc. into.** [sq
33e30 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
33e40 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f  *.** ^(If a memo
33e50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
33e60 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
33e70 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
33e80 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
33e90 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
33ea0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
33eb0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
33ec0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
33ed0 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
33ee0 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
33ef0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
33f00 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
33f10 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
33f20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
33f30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
33f40 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
33f50 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
33f60 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73  OMEM].)^.*/.cons
33f70 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
33f80 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
33f90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
33fa0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
33fb0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
33fc0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
33fd0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
33fe0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33ff0 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
34000 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f  *, int iCol);.do
34010 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
34020 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
34030 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
34040 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
34050 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
34060 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
34070 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  Col);.sqlite3_in
34080 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
34090 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
340a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
340b0 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
340c0 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
340d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
340e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
340f0 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  Col);.const void
34100 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
34110 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
34120 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
34130 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
34140 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
34150 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
34160 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  l);.sqlite3_valu
34170 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
34180 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
34190 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
341a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
341b0 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
341c0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
341d0 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55  Object.** DESTRU
341e0 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
341f0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
34200 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
34210 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
34220 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
34230 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34240 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
34250 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
34260 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
34270 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
34280 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
34290 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
342a0 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
342b0 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
342c0 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
342d0 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
342e0 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
342f0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
34300 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
34310 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
34320 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
34330 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
34340 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
34350 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
34360 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
34370 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
34380 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34390 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
343a0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
343b0 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
343c0 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
343d0 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
343e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
343f0 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
34400 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
34410 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
34420 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
34430 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
34440 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
34450 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
34460 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
34470 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
34480 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
34490 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
344a0 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
344b0 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
344c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
344d0 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
344e0 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
344f0 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
34500 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
34510 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
34520 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
34530 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
34540 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
34550 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
34560 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
34570 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
34580 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
34590 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
345a0 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
345b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
345c0 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
345d0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
345e0 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
345f0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
34600 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
34610 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
34620 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
34630 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
34640 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
34650 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
34660 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
34670 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74  rruption..*/.int
34680 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
34690 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
346a0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
346b0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
346c0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
346d0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45  ent Object.** ME
346e0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
346f0 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  mt.**.** The sql
34700 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
34710 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
34720 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
34730 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
34740 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
34750 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
34760 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
34770 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
34780 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
34790 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
347a0 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
347b0 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
347c0 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
347d0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
347e0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
347f0 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
34800 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
34810 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
34820 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
34830 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
34840 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
34850 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
34860 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
34870 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
34880 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
34890 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
348a0 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
348b0 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
348c0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
348d0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
348e0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
348f0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
34900 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
34910 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
34920 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
34930 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
34940 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
34950 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
34960 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
34970 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
34980 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
34990 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
349a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
349b0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
349c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
349d0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
349e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
349f0 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
34a00 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
34a10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
34a20 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
34a30 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
34a40 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
34a50 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
34a60 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
34a70 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
34a80 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
34a90 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
34aa0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
34ab0 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
34ac0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
34ad0 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74   S..*/.int sqlit
34ae0 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
34af0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
34b00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34b10 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
34b20 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
34b30 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
34b40 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
34b50 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
34b60 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
34b70 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
34b80 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
34b90 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
34ba0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
34bb0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d   functions}.** M
34bc0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
34bd0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
34be0 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
34bf0 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
34c00 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
34c10 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
34c20 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
34c30 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
34c40 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
34c50 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
34c60 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
34c70 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
34c80 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
34c90 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
34ca0 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
34cb0 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
34cc0 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65  s are the text e
34cd0 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64  ncoding expected
34ce0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f   for.** the seco
34cf0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
34d00 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
34d10 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65  nction being cre
34d20 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ated).** and the
34d30 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73   presence or abs
34d40 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75  ence of a destru
34d50 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f  ctor callback fo
34d60 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  r.** the applica
34d70 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
34d80 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
34d90 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
34da0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
34db0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
34dc0 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
34dd0 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
34de0 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
34df0 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
34e00 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
34e10 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
34e20 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
34e30 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
34e40 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
34e50 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
34e60 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
34e70 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
34e80 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
34e90 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
34ea0 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
34eb0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
34ec0 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
34ed0 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
34ee0 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
34ef0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
34f00 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
34f10 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
34f20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
34f30 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
34f40 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
34f50 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
34f60 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
34f70 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
34f80 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68  -8 bytes, not ch
34f90 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46  aracters nor UTF
34fa0 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20  -16 bytes.  .** 
34fb0 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20  ^Any attempt to 
34fc0 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
34fd0 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
34fe0 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
34ff0 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d  ult in [SQLITE_M
35000 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74  ISUSE] being ret
35010 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
35020 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
35030 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
35040 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
35050 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
35060 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
35070 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
35080 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
35090 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
350a0 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
350b0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
350c0 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
350d0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
350e0 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
350f0 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
35100 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
35110 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
35120 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
35130 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
35140 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
35150 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
35160 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
35170 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
35180 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
35190 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
351a0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
351b0 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
351c0 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
351d0 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
351e0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
351f0 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
35200 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
35210 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
35220 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
35230 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20  should set this 
35240 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
35250 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
35260 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   if the function
35270 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35280 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c  invokes .** [sql
35290 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
352a0 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70  6le()] on an inp
352b0 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ut, or [SQLITE_U
352c0 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a  TF16BE] if the.*
352d0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
352e0 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65   invokes [sqlite
352f0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
35300 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
35310 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   or.** [SQLITE_U
35320 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65  TF16] if [sqlite
35330 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
35340 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53  ] is used, or [S
35350 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f  QLITE_UTF8].** o
35360 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20  therwise.  ^The 
35370 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
35380 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
35390 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
353a0 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66  es using.** diff
353b0 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 20  erent preferred 
353c0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20  text encodings, 
353d0 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 69  with different i
353e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
353f0 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64  or.** each encod
35400 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75  ing..** ^When mu
35410 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
35420 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
35430 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
35440 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
35450 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
35460 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
35470 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
35480 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
35490 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
354a0 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
354b0 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e  meter may option
354c0 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74  ally be ORed wit
354d0 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d  h [SQLITE_DETERM
354e0 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73  INISTIC].** to s
354f0 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66  ignal that the f
35500 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77  unction will alw
35510 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73  ays return the s
35520 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e  ame result given
35530 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70  .** the same inp
35540 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e  uts within a sin
35550 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
35560 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e  t.  Most SQL fun
35570 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65  ctions are.** de
35580 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
35590 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64  e built-in [rand
355a0 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69  om()] SQL functi
355b0 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  on is an example
355c0 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   of a.** functio
355d0 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65  n that is not de
355e0 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
355f0 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 70  e SQLite query p
35600 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74  lanner is able t
35610 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64  o.** perform add
35620 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61  itional optimiza
35630 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69  tions on determi
35640 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73  nistic functions
35650 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74  , so use.** of t
35660 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  he [SQLITE_DETER
35670 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69  MINISTIC] flag i
35680 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68  s recommended wh
35690 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a  ere possible..**
356a0 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
356b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
356c0 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
356d0 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
356e0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
356f0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
35700 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
35710 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
35720 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
35730 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
35740 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
35750 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
35760 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
35770 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
35780 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
35790 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
357a0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
357b0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
357c0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
357d0 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
357e0 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
357f0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
35800 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
35810 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
35820 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
35830 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
35840 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
35850 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
35860 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
35870 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
35880 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
35890 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
358a0 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
358b0 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
358c0 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
358d0 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
358e0 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
358f0 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
35900 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
35910 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
35920 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
35930 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
35940 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
35950 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
35960 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
35970 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
35980 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
35990 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
359a0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
359b0 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
359c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
359d0 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
359e0 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
359f0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
35a00 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
35a10 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
35a20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
35a30 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
35a40 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
35a50 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
35a60 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
35a70 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
35a80 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
35a90 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
35aa0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
35ab0 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
35ac0 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
35ad0 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
35ae0 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
35af0 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
35b00 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
35b10 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
35b20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
35b30 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
35b40 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
35b50 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
35b60 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
35b70 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
35b80 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
35b90 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
35ba0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
35bb0 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
35bc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
35bd0 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
35be0 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
35bf0 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
35c00 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
35c10 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
35c20 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
35c30 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
35c40 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
35c50 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
35c60 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
35c70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
35c80 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
35c90 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
35ca0 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
35cb0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
35cc0 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
35cd0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35ce0 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
35cf0 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
35d00 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
35d10 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
35d20 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
35d30 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
35d40 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
35d50 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
35d60 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
35d70 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
35d80 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
35d90 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
35da0 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
35db0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
35dc0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
35dd0 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
35de0 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
35df0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
35e00 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
35e10 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
35e20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
35e30 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
35e40 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
35e50 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
35e60 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
35e70 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
35e80 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
35e90 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
35ea0 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
35eb0 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
35ec0 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
35ed0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
35ee0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
35ef0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35f00 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
35f10 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
35f20 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
35f30 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
35f40 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
35f50 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
35f60 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
35f70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
35f80 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
35f90 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
35fa0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
35fb0 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
35fc0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
35fd0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
35fe0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
35ff0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
36000 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
36010 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
36020 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
36030 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
36040 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
36050 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
36060 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
36070 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
36080 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
36090 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
360a0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
360b0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
360c0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
360d0 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
360e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
360f0 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
36100 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
36110 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
36120 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
36130 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
36140 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
36150 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
36160 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36170 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
36180 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
36190 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
361a0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
361b0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
361c0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
361d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
361e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
361f0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
36200 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
36210 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
36220 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
36230 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
36240 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
36250 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
36260 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
36270 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
36280 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
36290 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
362a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
362b0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
362c0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
362d0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
362e0 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69  context*),.  voi
362f0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
36300 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
36310 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
36320 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
36330 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
36340 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
36350 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
36360 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
36370 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
36380 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
36390 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
363a0 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
363b0 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a      1    /* IMP:
363c0 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a   R-37514-35566 *
363d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
363e0 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
363f0 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30  2    /* IMP: R-0
36400 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64  3371-37637 */.#d
36410 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
36420 31 36 42 45 20 20 20 20 20 20 20 20 33 20 20 20  16BE        3   
36430 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31   /* IMP: R-51971
36440 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e  -34154 */.#defin
36450 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
36460 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
36470 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
36480 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
36490 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
364a0 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44         5    /* D
364b0 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65  eprecated */.#de
364c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
364d0 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
364e0 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
364f0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
36500 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
36510 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c  REF: Function Fl
36520 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ags.**.** These 
36530 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65  constants may be
36540 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 77   ORed together w
36550 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
36560 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65  ITE_UTF8 | prefe
36570 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
36580 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74  ng] as the fourt
36590 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  h argument.** to
365a0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
365b0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73  _function()], [s
365c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
365d0 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  nction16()], or.
365e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
365f0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
36600 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
36610 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
36620 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a  IC    0x800../*.
36630 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70  ** CAPI3REF: Dep
36640 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e  recated Function
36650 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a  s.** DEPRECATED.
36660 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
36670 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65  tions are [depre
36680 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65  cated].  In orde
36690 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
366a0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
366b0 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
366c0 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20  der code, these 
366d0 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  functions contin
366e0 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70  ue .** to be sup
366f0 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72  ported.  However
36700 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  , new applicatio
36710 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ns should avoid.
36720 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
36730 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
36740 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f  To encourage pro
36750 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69  grammers to avoi
36760 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74  d.** these funct
36770 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f  ions, we will no
36780 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74  t explain what t
36790 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
367a0 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
367b0 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
367c0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
367d0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
367e0 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  e_count(sqlite3_
367f0 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
36800 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
36810 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64   sqlite3_expired
36820 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
36830 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
36840 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  ED int sqlite3_t
36850 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
36860 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
36870 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
36880 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
36890 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  D int sqlite3_gl
368a0 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
368b0 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
368c0 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74  CATED void sqlit
368d0 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75  e3_thread_cleanu
368e0 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  p(void);.SQLITE_
368f0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
36900 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
36910 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64  arm(void(*)(void
36920 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  *,sqlite3_int64,
36930 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20  int),.          
36940 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
36950 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
36960 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
36970 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
36980 69 6e 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a  ing SQL Values.*
36990 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
369a0 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68  3_value.**.** Th
369b0 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
369c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
369d0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
369e0 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
369f0 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
36a00 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
36a10 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
36a20 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
36a30 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
36a40 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
36a50 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  e.  .**.** The x
36a60 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
36a70 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
36a80 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
36a90 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
36aa0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
36ab0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
36ac0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
36ad0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
36ae0 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
36af0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
36b00 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
36b10 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
36b20 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
36b30 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
36b40 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
36b50 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
36b60 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
36b70 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
36b80 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36b90 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
36ba0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
36bb0 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
36bc0 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
36bd0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
36be0 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
36bf0 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
36c00 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
36c10 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
36c20 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36c30 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
36c40 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
36c50 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
36c60 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
36c70 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
36c80 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
36c90 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
36ca0 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
36cb0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
36cc0 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
36cd0 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
36ce0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
36cf0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
36d00 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
36d10 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
36d20 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
36d30 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
36d40 63 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20  cept that these 
36d50 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
36d60 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
36d70 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
36d80 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
36d90 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
36da0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
36db0 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
36dc0 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
36dd0 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
36de0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
36df0 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
36e00 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
36e10 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
36e20 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
36e30 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
36e40 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68  st machine.  ^Th
36e50 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
36e60 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
36e70 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
36e80 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
36e90 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
36ea0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
36eb0 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
36ec0 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
36ed0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
36ee0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
36ef0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
36f00 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
36f10 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
36f20 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
36f30 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
36f40 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
36f50 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
36f60 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
36f70 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
36f80 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
36f90 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
36fa0 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
36fb0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
36fc0 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
36fd0 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
36fe0 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
36ff0 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
37000 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
37010 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
37020 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
37030 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
37040 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
37050 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
37060 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
37070 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
37080 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
37090 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
370a0 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
370b0 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  )^.**.** Please 
370c0 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
370d0 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
370e0 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
370f0 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
37100 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
37110 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
37120 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37130 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
37140 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
37150 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
37160 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
37170 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
37180 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
37190 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
371a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
371b0 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
371c0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
371d0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
371e0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
371f0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
37200 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
37210 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
37220 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
37230 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
37240 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
37250 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
37260 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
37270 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
37280 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
37290 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
372a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
372b0 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
372c0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
372d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
372e0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
372f0 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  ue*);.double sql
37300 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
37310 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
37320 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
37330 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
37340 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65  _value*);.sqlite
37350 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
37360 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69  value_int64(sqli
37370 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
37380 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
37390 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
373a0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
373b0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
373c0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
373d0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
373e0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
373f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
37400 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  e_text16le(sqlit
37410 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
37420 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
37430 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
37440 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37450 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
37460 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  e_type(sqlite3_v
37470 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
37480 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
37490 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
374a0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
374b0 41 50 49 33 52 45 46 3a 20 46 69 6e 64 69 6e 67  API3REF: Finding
374c0 20 54 68 65 20 53 75 62 74 79 70 65 20 4f 66 20   The Subtype Of 
374d0 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45  SQL Values.** ME
374e0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61  THOD: sqlite3_va
374f0 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  lue.**.** The sq
37500 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74  lite3_value_subt
37510 79 70 65 28 56 29 20 66 75 6e 63 74 69 6f 6e 20  ype(V) function 
37520 72 65 74 75 72 6e 73 20 74 68 65 20 73 75 62 74  returns the subt
37530 79 70 65 20 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61  ype for.** an [a
37540 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
37550 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  ed SQL function]
37560 20 61 72 67 75 6d 65 6e 74 20 56 2e 20 20 54 68   argument V.  Th
37570 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 69 6e 66  e subtype.** inf
37580 6f 72 6d 61 74 69 6f 6e 20 63 61 6e 20 62 65 20  ormation can be 
37590 75 73 65 64 20 74 6f 20 70 61 73 73 20 61 20 6c  used to pass a l
375a0 69 6d 69 74 65 64 20 61 6d 6f 75 6e 74 20 6f 66  imited amount of
375b0 20 63 6f 6e 74 65 78 74 20 66 72 6f 6d 0a 2a 2a   context from.**
375c0 20 6f 6e 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   one SQL functio
375d0 6e 20 74 6f 20 61 6e 6f 74 68 65 72 2e 20 20 55  n to another.  U
375e0 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
375f0 72 65 73 75 6c 74 5f 73 75 62 74 79 70 65 28 29  result_subtype()
37600 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  ].** routine to 
37610 73 65 74 20 74 68 65 20 73 75 62 74 79 70 65 20  set the subtype 
37620 66 6f 72 20 74 68 65 20 72 65 74 75 72 6e 20 76  for the return v
37630 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 66  alue of an SQL f
37640 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53  unction..**.** S
37650 51 4c 69 74 65 20 6d 61 6b 65 73 20 6e 6f 20 75  QLite makes no u
37660 73 65 20 6f 66 20 73 75 62 74 79 70 65 20 69 74  se of subtype it
37670 73 65 6c 66 2e 20 20 49 74 20 6d 65 72 65 6c 79  self.  It merely
37680 20 70 61 73 73 65 73 20 74 68 65 20 73 75 62 74   passes the subt
37690 79 70 65 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ype.** from the 
376a0 72 65 73 75 6c 74 20 6f 66 20 6f 6e 65 20 5b 61  result of one [a
376b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
376c0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  ed SQL function]
376d0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6e 70   into the.** inp
376e0 75 74 20 6f 66 20 61 6e 6f 74 68 65 72 2e 0a 2a  ut of another..*
376f0 2f 0a 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73  /.unsigned int s
37700 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62  qlite3_value_sub
37710 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
37720 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
37730 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 20  I3REF: Copy And 
37740 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65 73 0a  Free SQL Values.
37750 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
37760 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e  e3_value.**.** ^
37770 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
37780 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61  e_dup(V) interfa
37790 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
377a0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
377b0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
377c0 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61   D and returns a
377d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
377e0 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 71   copy.  ^The [sq
377f0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 74  lite3_value] ret
37800 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70  urned.** is a [p
37810 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
37820 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65  _value] object e
37830 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70 75 74  ven if the input
37840 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65   is not..** ^The
37850 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
37860 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20  up(V) interface 
37870 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
37880 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20  V is NULL or if 
37890 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
378a0 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a  cation fails..**
378b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
378c0 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69  _value_free(V) i
378d0 6e 74 65 72 66 61 63 65 20 66 72 65 65 73 20 61  nterface frees a
378e0 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  n [sqlite3_value
378f0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76  ] object.** prev
37900 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
37910 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
37920 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66  lue_dup()].  ^If
37930 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   V is a NULL poi
37940 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  nter.** then sql
37950 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28  ite3_value_free(
37960 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  V) is a harmless
37970 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 73 71 6c 69 74   no-op..*/.sqlit
37980 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
37990 33 5f 76 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73  3_value_dup(cons
379a0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
379b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
379c0 76 61 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 74  value_free(sqlit
379d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
379e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
379f0 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
37a00 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
37a10 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
37a20 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  3_context.**.** 
37a30 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  Implementations 
37a40 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
37a50 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
37a60 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
37a70 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
37a80 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
37a90 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
37aa0 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
37ab0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
37ac0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
37ad0 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
37ae0 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
37af0 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
37b00 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
37b10 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
37b20 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
37b30 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
37b40 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
37b50 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
37b60 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
37b70 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
37b80 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
37b90 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
37ba0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
37bb0 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
37bc0 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
37bd0 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
37be0 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
37bf0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
37c00 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
37c10 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
37c20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
37c30 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
37c40 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
37c50 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
37c60 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
37c70 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
37c80 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
37c90 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
37ca0 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
37cb0 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
37cc0 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
37cd0 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
37ce0 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
37cf0 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
37d00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
37d10 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
37d20 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
37d30 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
37d40 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
37d50 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
37d60 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
37d70 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
37d80 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
37d90 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
37da0 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
37db0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37dc0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
37dd0 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
37de0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
37df0 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68  L pointer .** wh
37e00 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20  en first called 
37e10 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  if N is less tha
37e20 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
37e30 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  ro or if a memor
37e40 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72  y.** allocate er
37e50 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
37e60 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f  * ^(The amount o
37e70 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65  f space allocate
37e80 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67  d by sqlite3_agg
37e90 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
37ea0 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d  ,N) is.** determ
37eb0 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61  ined by the N pa
37ec0 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74  rameter on first
37ed0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
37ee0 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a  .  Changing the.
37ef0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e  ** value of N in
37f00 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
37f10 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
37f20 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
37f30 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61  within.** the sa
37f40 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
37f50 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77  ction instance w
37f60 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74  ill not resize t
37f70 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
37f80 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68  ocation.)^  With
37f90 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  in the xFinal ca
37fa0 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75  llback, it is cu
37fb0 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a  stomary to set.*
37fc0 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74  * N=0 in calls t
37fd0 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
37fe0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
37ff0 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20   so that no .** 
38000 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79  pointless memory
38010 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63   allocations occ
38020 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ur..**.** ^SQLit
38030 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
38040 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
38050 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
38060 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
38070 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
38080 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
38090 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
380a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
380b0 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
380c0 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
380d0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
380e0 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
380f0 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
38100 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
38110 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
38120 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
38130 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
38140 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
38150 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
38160 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
38170 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
38180 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
38190 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
381a0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
381b0 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
381c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
381d0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
381e0 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
381f0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
38200 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
38210 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
38220 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
38230 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
38240 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
38250 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
38260 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
38270 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
38280 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
38290 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
382a0 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
382b0 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
382c0 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
382d0 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
382e0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
382f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
38300 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
38310 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
38320 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
38330 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
38340 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
38350 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
38360 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
38370 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
38380 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
38390 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
383a0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
383b0 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
383c0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
383d0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
383e0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
383f0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
38400 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
38410 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38420 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
38430 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
38440 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
38450 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
38460 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
38470 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
38480 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
38490 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
384a0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
384b0 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
384c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
384d0 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
384e0 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
384f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
38500 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
38510 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
38520 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
38530 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
38540 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
38550 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
38560 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
38570 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  tion..*/.sqlite3
38580 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
38590 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
385a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
385b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
385c0 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
385d0 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f  ry Data.** METHO
385e0 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  D: sqlite3_conte
385f0 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  xt.**.** These f
38600 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
38610 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67  used by (non-agg
38620 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63  regate) SQL func
38630 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
38640 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
38650 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
38660 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
38670 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
38680 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
38690 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
386a0 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
386b0 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
386c0 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
386d0 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
386e0 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
386f0 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
38700 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
38710 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a  d.  An example.*
38720 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20  * of where this 
38730 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20  might be useful 
38740 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d  is in a regular-
38750 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
38760 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ing.** function.
38770 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
38780 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
38790 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
387a0 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73  can be stored as
387b0 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73  .** metadata ass
387c0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
387d0 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e   pattern string.
387e0 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f    .** Then as lo
387f0 6e 67 20 61 73