/ Hex Artifact Content
Login

Artifact 9ef801165ef597f8a57aa19a892206f4d6ad6854796c45de77fe402671573076:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65  LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 5b 76 65 72 73 69 6f  ** Since [versio
0f00: 6e 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65  n 3.6.18] ([date
0f10: 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a  of:3.6.18]), .**
0f20: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
0f30: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
0f40: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
0f50: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
0f60: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
0f70: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
0f80: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0f90: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
0fa0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
0fb0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
0fc0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
0fd0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
0fe0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
0ff0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
1000: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
1010: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
1020: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
1030: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
1040: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
1050: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
1060: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
1070: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
1080: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 20  -in (UTC) and a 
1090: 53 48 41 31 0a 2a 2a 20 6f 72 20 53 48 41 33 2d  SHA1.** or SHA3-
10a0: 32 35 36 20 68 61 73 68 20 6f 66 20 74 68 65 20  256 hash of the 
10b0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
10c0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
10d0: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
10e0: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
10f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1100: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1110: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1120: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1130: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1140: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1150: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1160: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
1170: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
1180: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1190: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
11a0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
11b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11c0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
11d0: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
11e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11f0: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1200: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1210: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1220: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71  lite3_version sq
1230: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a  lite3_sourceid.*
1240: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72  *.** These inter
1250: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68  faces provide th
1260: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
1270: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54  on as the [SQLIT
1280: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b  E_VERSION],.** [
1290: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
12a0: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c  UMBER], and [SQL
12b0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
12c0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
12d0: 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20  cros.** but are 
12e0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
12f0: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
1300: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
1310: 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69  r file.  ^(Cauti
1320: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65  ous.** programme
1330: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65  rs might include
1340: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
1350: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70  ents in their ap
1360: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
1370: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75  verify that valu
1380: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  es returned by t
1390: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
13a0: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73  match the macros
13b0: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65   in.** the heade
13c0: 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75  r, and thus ensu
13d0: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c  re that the appl
13e0: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f  ication is.** co
13f0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63  mpiled with matc
1400: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64  hing library and
1410: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a   header files..*
1420: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1430: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74  ><pre>.** assert
1440: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  ( sqlite3_libver
1450: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53  sion_number()==S
1460: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1470: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72  MBER );.** asser
1480: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1490: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
14a0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d  ITE_SOURCE_ID)==
14b0: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20  0 );.** assert( 
14c0: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c  strcmp(sqlite3_l
14d0: 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49  ibversion(),SQLI
14e0: 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29  TE_VERSION)==0 )
14f0: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1500: 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1510: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65   ^The sqlite3_ve
1520: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
1530: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73  onstant contains
1540: 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51   the text of [SQ
1550: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a  LITE_VERSION].**
1560: 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71   macro.  ^The sq
1570: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1580: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
1590: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
15a0: 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73   the.** to the s
15b0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
15c0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
15d0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  .  The sqlite3_l
15e0: 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66  ibversion().** f
15f0: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
1600: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44  ded for use in D
1610: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73  LLs since DLL us
1620: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e  ers usually do n
1630: 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63  ot have.** direc
1640: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
1650: 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74  ng constants wit
1660: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54  hin the DLL.  ^T
1670: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  he.** sqlite3_li
1680: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1690: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
16a0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71  ns an integer eq
16b0: 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ual to.** [SQLIT
16c0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
16d0: 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
16e0: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63  _sourceid() func
16f0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a  tion returns .**
1700: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1710: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
1720: 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74  whose value is t
1730: 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a  he same as the .
1740: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  ** [SQLITE_SOURC
1750: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
1760: 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  ssor macro..**.*
1770: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1780: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
1790: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
17a0: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  e_id()]..*/.SQLI
17b0: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20  TE_EXTERN const 
17c0: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
17d0: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68  sion[];.const ch
17e0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
17f0: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f  ersion(void);.co
1800: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1810: 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29  3_sourceid(void)
1820: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  ;.int sqlite3_li
1830: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1840: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
1850: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1860: 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61   Library Compila
1870: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61  tion Options Dia
1880: 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e  gnostics.**.** ^
1890: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
18a0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
18b0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
18c0: 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64  s 0 or 1 .** ind
18d0: 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20  icating whether 
18e0: 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70  the specified op
18f0: 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64  tion was defined
1900: 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20   at .** compile 
1910: 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49  time.  ^The SQLI
1920: 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62  TE_ prefix may b
1930: 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  e omitted from t
1940: 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61  he .** option na
1950: 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c  me passed to sql
1960: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1970: 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a  on_used().  .**.
1980: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
19a0: 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c  t() function all
19b0: 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a  ows iterating.**
19c0: 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f   over the list o
19d0: 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77  f options that w
19e0: 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63  ere defined at c
19f0: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a  ompile time by.*
1a00: 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20  * returning the 
1a10: 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d  N-th compile tim
1a20: 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e  e option string.
1a30: 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f    ^If N is out o
1a40: 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69  f range,.** sqli
1a50: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1a60: 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20  n_get() returns 
1a70: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1a80: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a   ^The SQLITE_ .*
1a90: 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74  * prefix is omit
1aa0: 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72  ted from any str
1ab0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1ac0: 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d   .** sqlite3_com
1ad0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ae0: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74  ..**.** ^Support
1af0: 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73   for the diagnos
1b00: 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71  tic functions sq
1b10: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1b20: 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e  ion_used().** an
1b30: 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  d sqlite3_compil
1b40: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61  eoption_get() ma
1b50: 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20  y be omitted by 
1b60: 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a  specifying the .
1b70: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  ** [SQLITE_OMIT_
1b80: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1b90: 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63  AGS] option at c
1ba0: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a  ompile time..**.
1bb0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c  ** See also: SQL
1bc0: 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69   functions [sqli
1bd0: 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  te_compileoption
1be0: 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1bf0: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f  [sqlite_compileo
1c00: 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64  ption_get()] and
1c10: 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70   the [compile_op
1c20: 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a  tions pragma]..*
1c30: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
1c40: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54  _OMIT_COMPILEOPT
1c50: 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73 71  ION_DIAGS.int sq
1c60: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c70: 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63  ion_used(const c
1c80: 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a  har *zOptName);.
1c90: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1ca0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1cb0: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
1cc0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1cd0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
1ce0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
1cf0: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
1d00: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d10: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
1d20: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1d30: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
1d40: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
1d50: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1d60: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
1d70: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
1d80: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
1d90: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
1da0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
1db0: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
1dc0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
1dd0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1de0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1df0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1e00: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1e10: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1e20: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
1e30: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
1e40: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1e50: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1e60: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
1e70: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1e80: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
1e90: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
1ea0: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1eb0: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1ec0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1ed0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1ee0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
1ef0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
1f00: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
1f10: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
1f20: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
1f30: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
1f40: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1f50: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1f60: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
1f70: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
1f80: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
1f90: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
1fa0: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
1fb0: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
1fc0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1fd0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
1fe0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
1ff0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
2000: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
2010: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
2020: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
2030: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
2040: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
2050: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
2060: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
2070: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
2080: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
2090: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
20a0: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
20b0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
20c0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
20d0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
20e0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
20f0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
2100: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
2110: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
2120: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
2130: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
2140: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2150: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
2160: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
2170: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
2180: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
2190: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
21a0: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
21b0: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
21c0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
21d0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
21e0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
21f0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2200: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
2210: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2220: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
2230: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2240: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e  _SERIALIZED].  ^
2250: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
2260: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
2270: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2280: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2290: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
22a0: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
22b0: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
22c0: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
22d0: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
22e0: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
22f0: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2300: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2310: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2320: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
2330: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2340: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
2350: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
2360: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2370: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
2380: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2390: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
23a0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
23b0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
23c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
23d0: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
23e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
23f0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2400: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2410: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2420: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
2430: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2440: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
2450: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
2460: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
2470: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
2480: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2490: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
24a0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
24b0: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
24c0: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
24d0: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
24e0: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
24f0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2500: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2510: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2520: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2530: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
2540: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
2550: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
2560: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2570: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
2580: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2590: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
25a0: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
25b0: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
25c0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
25d0: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
25e0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
25f0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2600: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
2610: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
2620: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
2630: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
2640: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
2650: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
2660: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
2670: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2680: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
2690: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
26a0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
26b0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
26c0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
26d0: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
26e0: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
26f0: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
2700: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
2710: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
2720: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
2730: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
2740: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
2750: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
2760: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
2770: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2780: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
2790: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
27a0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
27b0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
27c0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
27d0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
27e0: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
27f0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
2800: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
2810: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
2820: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
2830: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
2840: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
2850: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2860: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
2870: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2880: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
2890: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
28a0: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
28b0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
28c0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
28d0: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
28e0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
28f0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
2900: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
2910: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
2920: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
2930: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
2940: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2950: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2960: 65 5f 69 6e 74 36 34 3b 0a 23 20 69 66 64 65 66  e_int64;.# ifdef
2970: 20 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54   SQLITE_UINT64_T
2980: 59 50 45 0a 20 20 20 20 74 79 70 65 64 65 66 20  YPE.    typedef 
2990: 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54 59  SQLITE_UINT64_TY
29a0: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
29b0: 3b 0a 23 20 65 6c 73 65 20 20 0a 20 20 20 20 74  ;.# else  .    t
29c0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
29d0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
29e0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
29f0: 0a 23 20 65 6e 64 69 66 0a 23 65 6c 69 66 20 64  .# endif.#elif d
2a00: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2a10: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2a20: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2a30: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2a40: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2a50: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2a60: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2a70: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
2a80: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
2a90: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
2aa0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2ab0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
2ac0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2ad0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2ae0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2af0: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2b00: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2b10: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2b20: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2b30: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2b40: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2b50: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2b60: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2b70: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
2b80: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
2b90: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
2ba0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
2bb0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
2bc0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
2bd0: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2be0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2bf0: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2c00: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45  Connection.** DE
2c10: 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2c20: 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
2c30: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
2c40: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2c50: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
2c60: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
2c70: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
2c80: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
2c90: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2ca0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2cb0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
2cc0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2cd0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ce0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2cf0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2d00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2d10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2d20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2d30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2d40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2d50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2d60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2d70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2d90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2da0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2db0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2dc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2dd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2de0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2df0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2e00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2e10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2e20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2e30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2e40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2e50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72  ements.** and/or
2e60: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2e70: 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65  te3_backups, the
2e80: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
2e90: 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65  onnection become
2ea0: 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65  s.** an unusable
2eb0: 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20   "zombie" which 
2ec0: 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
2ed0: 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ly be deallocate
2ee0: 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61  d when the.** la
2ef0: 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
2f00: 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a  ement is finaliz
2f10: 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73  ed or the last s
2f20: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73  qlite3_backup is
2f30: 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54  .** finished.  T
2f40: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  he sqlite3_close
2f50: 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
2f60: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
2f70: 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74  use with.** host
2f80: 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20   languages that 
2f90: 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c  are garbage coll
2fa0: 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65  ected, and where
2fb0: 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68   the order in wh
2fc0: 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f  ich.** destructo
2fd0: 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73  rs are called is
2fe0: 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a   arbitrary..**.*
2ff0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
3000: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
3010: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
3020: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
3030: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a  d statements],.*
3040: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
3050: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61  close | close] a
3060: 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ll [BLOB handles
3070: 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  ], and .** [sqli
3080: 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73  te3_backup_finis
3090: 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20  h | finish] all 
30a0: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
30b0: 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61   objects associa
30c0: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
30d0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
30e0: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
30f0: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
3100: 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a  e object.  ^If.*
3110: 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  * sqlite3_close_
3120: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  v2() is called o
3130: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
3140: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
3150: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
3160: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
3170: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
3180: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
3190: 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  nd/or.** [sqlite
31a0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31b0: 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  s then it return
31c0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e  s [SQLITE_OK] an
31d0: 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69  d the deallocati
31e0: 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63  on.** of resourc
31f0: 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75  es is deferred u
3200: 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72  ntil all [prepar
3210: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
3220: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a  [BLOB handles],.
3230: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
3240: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3250: 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79  are also destroy
3260: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3270: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3280: 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77  t is destroyed w
3290: 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69  hile a transacti
32a0: 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74  on is open,.** t
32b0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
32c0: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
32d0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
32e0: 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74  ** The C paramet
32f0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
3300: 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71  lose(C)] and [sq
3310: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43  lite3_close_v2(C
3320: 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
3330: 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  ther a NULL.** p
3340: 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71  ointer or an [sq
3350: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f  lite3] object po
3360: 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a  inter obtained.*
3370: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3380: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
3390: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a  3_open16()], or.
33a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
33b0: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
33c0: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
33d0: 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  d..** ^Calling s
33e0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f  qlite3_close() o
33f0: 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  r sqlite3_close_
3400: 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  v2() with a NULL
3410: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75   pointer.** argu
3420: 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65  ment is a harmle
3430: 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74  ss no-op..*/.int
3440: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73   sqlite3_close(s
3450: 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20 73 71  qlite3*);.int sq
3460: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73  lite3_close_v2(s
3470: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
3480: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20   The type for a 
3490: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
34a0: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65  n..** This is le
34b0: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61  gacy and depreca
34c0: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c  ted.  It is incl
34d0: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  uded for histori
34e0: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  cal.** compatibi
34f0: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  lity and is not 
3500: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74  documented..*/.t
3510: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c  ypedef int (*sql
3520: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76  ite3_callback)(v
3530: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
3540: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a   char**);../*.**
3550: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53   CAPI3REF: One-S
3560: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74  tep Query Execut
3570: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a  ion Interface.**
3580: 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
3590: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
35a0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
35b0: 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69  ace is a conveni
35c0: 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f  ence wrapper aro
35d0: 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
35e0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
35f0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
3600: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
3610: 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68  nalize()],.** th
3620: 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70  at allows an app
3630: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20  lication to run 
3640: 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65  multiple stateme
3650: 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69  nts of SQL.** wi
3660: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20  thout having to 
3670: 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63  use a lot of C c
3680: 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode. .**.** ^The
3690: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
36a0: 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a  interface runs z
36b0: 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d  ero or more UTF-
36c0: 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65  8 encoded,.** se
36d0: 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
36e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
36f0: 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20  passed into its 
3700: 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a  2nd argument,.**
3710: 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20   in the context 
3720: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
3730: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73   connection] pas
3740: 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73  sed in as its 1s
3750: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  t.** argument.  
3760: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3770: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65   function of the
3780: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3790: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
37a0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  () is not NULL, 
37b0: 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b  then it is invok
37c0: 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75  ed for each resu
37d0: 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67  lt row.** coming
37e0: 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c   out of the eval
37f0: 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  uated SQL statem
3800: 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20  ents.  ^The 4th 
3810: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73  argument to.** s
3820: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3830: 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68   relayed through
3840: 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75   to the 1st argu
3850: 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20  ment of each.** 
3860: 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74  callback invocat
3870: 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ion.  ^If the ca
3880: 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74  llback pointer t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  .** is NULL, the
38b0: 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73  n no callback is
38c0: 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e   ever invoked an
38d0: 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72  d result rows ar
38e0: 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  e.** ignored..**
38f0: 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72  .** ^If an error
3900: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76   occurs while ev
3910: 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c  aluating the SQL
3920: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
3930: 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  ed into.** sqlit
3940: 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20  e3_exec(), then 
3950: 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
3960: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65   current stateme
3970: 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20  nt stops and.** 
3980: 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65  subsequent state
3990: 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65  ments are skippe
39a0: 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20  d.  ^If the 5th 
39b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
39c0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69  ite3_exec().** i
39d0: 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
39e0: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67  any error messag
39f0: 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  e is written int
3a00: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
3a10: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3a20: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
3a30: 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72   passed back thr
3a40: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72  ough the 5th par
3a50: 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76  ameter..** To av
3a60: 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73  oid memory leaks
3a70: 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
3a80: 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20  n should invoke 
3a90: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
3aa0: 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73  .** on error mes
3ab0: 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74  sage strings ret
3ac0: 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68  urned through th
3ad0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3ae0: 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  of.** sqlite3_ex
3af0: 65 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65  ec() after the e
3b00: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
3b10: 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ing is no longer
3b20: 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20   needed..** ^If 
3b30: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3b40: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3b50: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  c() is not NULL 
3b60: 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  and no errors.**
3b70: 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c   occur, then sql
3b80: 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73  ite3_exec() sets
3b90: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20   the pointer in 
3ba0: 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65  its 5th paramete
3bb0: 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66  r to.** NULL bef
3bc0: 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
3bd0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69  *.** ^If an sqli
3be0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3bf0: 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
3c00: 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65  zero, the sqlite
3c10: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74  3_exec().** rout
3c20: 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ine returns SQLI
3c30: 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74  TE_ABORT without
3c40: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61   invoking the ca
3c50: 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64  llback again and
3c60: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e  .** without runn
3c70: 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65  ing any subseque
3c80: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  nt SQL statement
3c90: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e  s..**.** ^The 2n
3ca0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3cb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3cc0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3cd0: 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  on is the.** num
3ce0: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
3cf0: 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e  n the result.  ^
3d00: 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  The 3rd argument
3d10: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
3d20: 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61  exec().** callba
3d30: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ck is an array o
3d40: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
3d50: 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61  rings obtained a
3d60: 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  s if from.** [sq
3d70: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
3d80: 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61  t()], one for ea
3d90: 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20  ch column.  ^If 
3da0: 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a  an element of a.
3db0: 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73  ** result row is
3dc0: 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
3dd0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72  orresponding str
3de0: 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ing pointer for 
3df0: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3e00: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3e10: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
3e20: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
3e30: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73  ment to the.** s
3e40: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3e50: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
3e60: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
3e70: 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20  o strings where 
3e80: 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65  each.** entry re
3e90: 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d  presents the nam
3ea0: 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69  e of correspondi
3eb0: 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ng result column
3ec0: 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20   as obtained.** 
3ed0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
3ee0: 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a  lumn_name()]..**
3ef0: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20  .** ^If the 2nd 
3f00: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3f10: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61  ite3_exec() is a
3f20: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61   NULL pointer, a
3f30: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61   pointer.** to a
3f40: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
3f50: 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61  or a pointer tha
3f60: 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20  t contains only 
3f70: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f  whitespace and/o
3f80: 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e  r .** SQL commen
3f90: 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20  ts, then no SQL 
3fa0: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
3fb0: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65  valuated and the
3fc0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
3fd0: 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  not changed..**.
3fe0: 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a  ** Restrictions:
3ff0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
4000: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4010: 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72 65 20  ion must ensure 
4020: 74 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72  that the 1st par
4030: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4040: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20  3_exec().**     
4050: 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20   is a valid and 
4060: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
4070: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c  onnection]..** <
4080: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4090: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ion must not clo
40a0: 73 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  se the [database
40b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
40c0: 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
40d0: 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65    the 1st parame
40e0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
40f0: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
4100: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
4110: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  nning..** <li> T
4120: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
4130: 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  ust not modify t
4140: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
4150: 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74   text passed int
4160: 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e  o.**      the 2n
4170: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
4180: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
4190: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
41a0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
41b0: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ul>.*/.int s
41c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
41d0: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
4200: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
4210: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
4220: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
4230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
4240: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
4250: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
4260: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
4270: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
4280: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
4290: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
42a0: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74            /* 1st
42d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
42e0: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
42f0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
4300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4310: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
4320: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
4330: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
4340: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
4350: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4360: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65   {result code de
4370: 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  finitions}.**.**
4380: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
4390: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
43a0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
43b0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
43c0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
43d0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
43e0: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
43f0: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
4400: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
4410: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
4420: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
4430: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4440: 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e  See also: [exten
4450: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4460: 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a  definitions].*/.
4470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4480: 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20  K           0   
4490: 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65  /* Successful re
44a0: 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e  sult */./* begin
44b0: 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f  ning-of-error-co
44c0: 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  des */.#define S
44d0: 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20  QLITE_ERROR     
44e0: 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72     1   /* SQL er
44f0: 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64  ror or missing d
4500: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4510: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e  ne SQLITE_INTERN
4520: 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e  AL     2   /* In
4530: 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72  ternal logic err
4540: 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a  or in SQLite */.
4550: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4560: 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20  ERM         3   
4570: 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73  /* Access permis
4580: 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  sion denied */.#
4590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
45a0: 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f  ORT        4   /
45b0: 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  * Callback routi
45c0: 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20  ne requested an 
45d0: 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65  abort */.#define
45e0: 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20   SQLITE_BUSY    
45f0: 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20       5   /* The 
4600: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
4610: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4620: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
4630: 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20         6   /* A 
4640: 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74  table in the dat
4650: 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20  abase is locked 
4660: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4670: 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37  E_NOMEM        7
4680: 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29     /* A malloc()
4690: 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69   failed */.#defi
46a0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
46b0: 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74  LY     8   /* At
46c0: 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61  tempt to write a
46d0: 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61   readonly databa
46e0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
46f0: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20  LITE_INTERRUPT  
4700: 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69    9   /* Operati
4710: 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79  on terminated by
4720: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
4730: 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pt()*/.#define S
4740: 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20  QLITE_IOERR     
4750: 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b    10   /* Some k
4760: 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20  ind of disk I/O 
4770: 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a  error occurred *
4780: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4790: 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20  _CORRUPT     11 
47a0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
47b0: 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20  e disk image is 
47c0: 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65  malformed */.#de
47d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46  fine SQLITE_NOTF
47e0: 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20  OUND    12   /* 
47f0: 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69  Unknown opcode i
4800: 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63  n sqlite3_file_c
4810: 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66  ontrol() */.#def
4820: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20  ine SQLITE_FULL 
4830: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49         13   /* I
4840: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20  nsertion failed 
4850: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65  because database
4860: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66   is full */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
4880: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55  PEN    14   /* U
4890: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68  nable to open th
48a0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
48b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
48c0: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35  E_PROTOCOL    15
48d0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c     /* Database l
48e0: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
48f0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4900: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
4910: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
4920: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
4930: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
4940: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4950: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
4960: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
4970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
4980: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
4990: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
49a0: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
49b0: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
49c0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
49d0: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
49e0: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
49f0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
4a00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4a10: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4a20: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4a30: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
4a40: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4a50: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
4a60: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
4a70: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
4a80: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
4a90: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4aa0: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4ab0: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4ac0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4ad0: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4ae0: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4af0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4b00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4b10: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4b20: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
4b30: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
4b40: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4b50: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
4b60: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
4b70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4b80: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
4b90: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
4ba0: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
4bb0: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
4bc0: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
4bd0: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
4be0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4bf0: 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20  ITE_NOTICE      
4c00: 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61  27   /* Notifica
4c10: 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74  tions from sqlit
4c20: 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66  e3_log() */.#def
4c30: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
4c40: 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57  NG     28   /* W
4c50: 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c  arnings from sql
4c60: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57  efine SQLITE_ROW
4c80: 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a           100  /*
4c90: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4ca0: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  has another row 
4cb0: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ready */.#define
4cc0: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20   SQLITE_DONE    
4cd0: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69      101  /* sqli
4ce0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66  te3_step() has f
4cf0: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
4d00: 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65  g */./* end-of-e
4d10: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f  rror-codes */../
4d20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
4d30: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
4d40: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
4d50: 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : {extended resu
4d60: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4d70: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74  ons}.**.** In it
4d80: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  s default config
4d90: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20  uration, SQLite 
4da0: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74  API routines ret
4db0: 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e  urn one of 30 in
4dc0: 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74  teger.** [result
4dd0: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4de0: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4df0: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
4e00: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
4e10: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
4e20: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
4e30: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
4e40: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
4e50: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4e60: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4e70: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4e80: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4e90: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4ea0: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4eb0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4ec0: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4ed0: 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33 2e 38  .8 [dateof:3.3.8
4ee0: 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72 29 20  ].** and later) 
4ef0: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4f00: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4f10: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4f20: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4f30: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4f40: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4f50: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
4f60: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f70: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
4f80: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4f90: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4fa0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4fb0: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4fc0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4fd0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4fe0: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
4ff0: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
5000: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
5010: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
5020: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
5030: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
5040: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
5050: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5060: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5070: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5080: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5090: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50a0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
50b0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
50c0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
50d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50e0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
50f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5100: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5110: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5120: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5130: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5140: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5180: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
51a0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
51b0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
51c0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
51d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51e0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
51f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5200: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5220: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5230: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5240: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5250: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5260: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5270: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5280: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5290: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52a0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
52b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52c0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
52d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52e0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
52f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5300: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5310: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5320: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5330: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5340: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5350: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5360: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5370: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5380: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5390: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53a0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
53b0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
53c0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
53d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53e0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
53f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5400: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5410: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5420: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5430: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5440: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5450: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5460: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5470: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5480: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5490: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54a0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
54b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54c0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
54d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54e0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
54f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5500: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5510: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5520: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5530: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5540: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5550: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5560: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5570: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5580: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5590: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55a0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
55b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55c0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
55d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55e0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
55f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5600: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5620: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5630: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5640: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5650: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5660: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5670: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5680: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5690: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56a0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
56b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56c0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
56d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56e0: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
56f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5700: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
5710: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5720: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
5730: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5740: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
5750: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5760: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5770: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5780: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
57a0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
57b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
57c0: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
57d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
57e0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
57f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5800: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5820: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5830: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5840: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5860: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5870: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5880: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5890: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
58a0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
58b0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
58c0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
58d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
58e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
58f0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5900: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5910: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5920: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5930: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
5940: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
5950: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5960: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5970: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5980: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5990: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
59a0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
59b0: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
59c0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
59d0: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
59e0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
59f0: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5a00: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5a10: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5a30: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5a50: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
5a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
5a70: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
5a80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
5a90: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5aa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5ab0: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5ac0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5ad0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5af0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5b00: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5b10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b40: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
5b50: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b60: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5b70: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5b80: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
5b90: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5ba0: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5bc0: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5bd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5be0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5bf0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5c00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5c10: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5c20: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5c30: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5c40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c50: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
5c60: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c70: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
5c80: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5c90: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5ca0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5cb0: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5cd0: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5ce0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5cf0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5d00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5d20: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5d30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5d40: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5d50: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5d60: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5d70: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5d80: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5d90: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5da0: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5db0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5dc0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5dd0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5de0: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5df0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5e00: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5e10: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
5e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
5e30: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
5e40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5e50: 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52  LITE_OK_LOAD_PER
5e60: 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53 51  MANENTLY     (SQ
5e70: 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29  LITE_OK | (1<<8)
5e80: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5e90: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5ea0: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5eb0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5ec0: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5ed0: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5ee0: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5ef0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5f00: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5f10: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
5f20: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
5f30: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5f40: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
5f50: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
5f60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f70: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5f80: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5f90: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5fa0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5fb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5fc0: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5fd0: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5fe0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5ff0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6010: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
6020: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
6030: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6040: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6060: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
6070: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
6080: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60a0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
60b0: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
60c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
60d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60e0: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
60f0: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
6100: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6120: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
6130: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
6140: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6150: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6170: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
6180: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
6190: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
61a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
61b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61c0: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
61d0: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
61e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6200: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
6210: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
6220: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6240: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
6250: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
6260: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6280: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
6290: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
62a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62c0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
62d0: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
62e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6300: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
6310: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
6320: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6340: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
6350: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
6360: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6380: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
6390: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
63a0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
63b0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
63c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
63d0: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
63e0: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
63f0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6400: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6420: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
6430: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
6440: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6450: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6470: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
6480: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
6490: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
64a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
64b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
64c0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
64d0: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
64e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
64f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6500: 5f 46 49 4c 45 50 52 4f 54 45 43 54 49 4f 4e 5f  _FILEPROTECTION_
6510: 4d 41 53 4b 20 20 20 20 20 20 20 20 20 20 20 20  MASK            
6520: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6530: 20 20 20 20 20 30 78 30 30 37 30 30 30 30 30 0a       0x00700000.
6540: 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20  ./* Reserved:   
6550: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6560: 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30        0x00F00000
6570: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
6580: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
6590: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
65a0: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
65b0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
65c0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
65d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
65e0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
65f0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
6600: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
6610: 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  f these.** bit v
6620: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
6630: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
6640: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
6650: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
6660: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
6670: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
6680: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6690: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
66a0: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
66b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
66c0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
66d0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
66e0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
66f0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6700: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6710: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
6720: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
6730: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
6740: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
6750: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
6760: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
6770: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
6780: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
6790: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
67a0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
67b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
67c0: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
67d0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
67e0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
67f0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
6800: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
6810: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
6820: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
6830: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
6840: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
6850: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
6860: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6870: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
6880: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6890: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
68a0: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
68b0: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
68c0: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
68d0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20  ** to xWrite(). 
68e0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
68f0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6900: 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d  WRITE property m
6910: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74  eans that.** aft
6920: 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77  er reboot follow
6930: 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70  ing a crash or p
6940: 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f  ower loss, the o
6950: 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a  nly bytes in a.*
6960: 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65  * file that were
6970: 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20   written at the 
6980: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65  application leve
6990: 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61  l might have cha
69a0: 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74  nged.** and that
69b0: 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c   adjacent bytes,
69c0: 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68   even bytes with
69d0: 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74  in the same sect
69e0: 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e  or are.** guaran
69f0: 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61  teed to be uncha
6a00: 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54  nged.  The SQLIT
6a10: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
6a20: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a  BLE_WHEN_OPEN.**
6a30: 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20   flag indicates 
6a40: 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e  that a file cann
6a50: 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68  ot be deleted wh
6a60: 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a  en open.  The.**
6a70: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d   SQLITE_IOCAP_IM
6a80: 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64  MUTABLE flag ind
6a90: 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
6aa0: 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65  file is on.** re
6ab0: 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e  ad-only media an
6ac0: 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  d cannot be chan
6ad0: 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63  ged even by proc
6ae0: 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c  esses with.** el
6af0: 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65  evated privilege
6b00: 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s..*/.#define SQ
6b10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6b20: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
6b30: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
6b40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b50: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
6b60: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6b70: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
6b80: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
6b90: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6ba0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
6bb0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6bc0: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
6bd0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6be0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
6bf0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20  _IOCAP_ATOMIC4K 
6c00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6c10: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
6c20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6c30: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20  OMIC8K          
6c40: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
6c50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6c60: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
6c70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6c80: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
6c90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6ca0: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20  IC32K           
6cb0: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
6cc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6cd0: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
6ce0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6cf0: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
6d00: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
6d10: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20  PPEND           
6d20: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
6d30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6d40: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
6d50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34          0x000004
6d60: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6d70: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
6d80: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30  BLE_WHEN_OPEN  0
6d90: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e  x00000800.#defin
6da0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
6db0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
6dc0: 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30  TE    0x00001000
6dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6de0: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20  IOCAP_IMMUTABLE 
6df0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6e00: 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0002000../*.** C
6e10: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
6e20: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
6e30: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
6e40: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
6e50: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
6e60: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
6e70: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
6e80: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
6e90: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
6ea0: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
6eb0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
6ec0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6ed0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6ee0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
6ef0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
6f00: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
6f10: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
6f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6f30: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
6f40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6f50: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
6f60: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
6f70: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
6f80: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
6f90: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
6fa0: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
6fb0: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
6fc0: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
6fd0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
6fe0: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
6ff0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7000: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
7010: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
7020: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
7030: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
7040: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
7050: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
7060: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7070: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
7080: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
7090: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
70a0: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
70b0: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
70c0: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
70d0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
70e0: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
70f0: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
7100: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
7110: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
7120: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
7130: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
7140: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
7150: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
7160: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
7170: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
7180: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
7190: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
71a0: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
71b0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
71c0: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
71d0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
71e0: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
71f0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
7200: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
7210: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
7220: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
7230: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
7240: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
7250: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
7260: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
7270: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
7280: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
7290: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
72a0: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
72b0: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
72c0: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
72d0: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
72e0: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
72f0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
7300: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
7310: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
7320: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
7330: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
7340: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
7350: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
7360: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
7370: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
7380: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
7390: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
73a0: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
73b0: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
73c0: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
73d0: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
73e0: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
73f0: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
7400: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
7410: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
7420: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
7430: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
7440: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
7450: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
7460: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
7470: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
7480: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
7490: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
74a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
74b0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
74c0: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
74d0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
74e0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
74f0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
7500: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7510: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
7520: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7530: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
7540: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
7550: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
7560: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
7570: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
7580: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
7590: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
75a0: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
75b0: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
75c0: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
75d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
75e0: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
75f0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
7600: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
7610: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
7620: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
7630: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
7640: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
7650: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
7660: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
7670: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
7680: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
7690: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
76a0: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
76b0: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
76c0: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
76d0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
76e0: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
76f0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
7700: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
7710: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
7720: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
7730: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
7740: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
7750: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
7760: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7770: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
7780: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
7790: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
77a0: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
77b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
77c0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
77d0: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
77e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
77f0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
7800: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
7810: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
7820: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7830: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
7840: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
7850: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
7860: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
7870: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
7880: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
7890: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
78a0: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
78b0: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
78c0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
78d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
78e0: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
78f0: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
7900: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7910: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
7920: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7930: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
7940: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
7950: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
7960: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7970: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
7980: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
7990: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
79a0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
79b0: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
79c0: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
79d0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
79e0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
79f0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
7a00: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
7a10: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
7a20: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
7a30: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7a40: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
7a50: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7a60: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
7a70: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
7a80: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7a90: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
7aa0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
7ab0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
7ac0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
7ad0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
7ae0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
7af0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
7b00: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
7b10: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
7b20: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
7b30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
7b40: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
7b50: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
7b60: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
7b70: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
7b80: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
7b90: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
7ba0: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
7bb0: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
7bc0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
7bd0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
7be0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
7bf0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
7c00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7c10: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
7c20: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
7c30: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
7c40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
7c50: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
7c60: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
7c70: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
7c80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
7c90: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
7ca0: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
7cb0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
7cc0: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
7cd0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
7ce0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
7cf0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
7d00: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
7d10: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
7d20: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
7d30: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
7d40: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
7d50: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
7d60: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
7d70: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
7d80: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
7d90: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
7da0: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
7db0: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
7dc0: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
7dd0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
7de0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
7df0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
7e00: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
7e10: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
7e20: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
7e30: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7e40: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
7e50: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
7e60: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
7e70: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
7e80: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
7e90: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
7ea0: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
7eb0: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
7ec0: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
7ed0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
7ee0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
7ef0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
7f00: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
7f10: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
7f20: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
7f30: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
7f40: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
7f50: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
7f60: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
7f70: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
7f80: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
7f90: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
7fa0: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
7fb0: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
7fc0: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
7fd0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
7fe0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
7ff0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
8000: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
8010: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
8020: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
8030: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
8040: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
8050: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
8060: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
8070: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
8080: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
8090: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A [file control 
80a0: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f  opcodes | list o
80b0: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
80c0: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
80d0: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
80e0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
80f0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
8100: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
8110: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
8120: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
8130: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
8140: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
8150: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8160: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
8170: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
8180: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
8190: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
81a0: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
81b0: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
81c0: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
81d0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
81e0: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
81f0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
8200: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
8210: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
8220: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
8230: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
8240: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
8250: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
8260: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
8270: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
8280: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
8290: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
82a0: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
82b0: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
82c0: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
82d0: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
82e0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
82f0: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
8300: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
8310: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8320: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8330: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
8340: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
8350: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8360: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8370: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
8380: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8390: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
83a0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
83b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
83c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
83d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
83e0: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
83f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8400: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
8410: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8420: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
8430: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8440: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
8450: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8460: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c  EQUENTIAL].** <l
8470: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8480: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
8490: 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20  N_OPEN].** <li> 
84a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
84b0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
84c0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
84d0: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
84e0: 4c 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  LE].** </ul>.**.
84f0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
8500: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
8510: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
8520: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
8530: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
8540: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
8550: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
8560: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
8570: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
8580: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
8590: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
85a0: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
85b0: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
85c0: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
85d0: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
85e0: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
85f0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
8600: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
8610: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
8620: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
8630: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
8640: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
8650: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
8660: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
8670: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
8680: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
8690: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
86a0: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
86b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
86c0: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
86d0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
86e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
86f0: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
8700: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
8710: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
8720: 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  xWrite()..**.** 
8730: 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72  If xRead() retur
8740: 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ns SQLITE_IOERR_
8750: 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75  SHORT_READ it mu
8760: 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20  st also fill.** 
8770: 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f  in the unread po
8780: 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  rtions of the bu
8790: 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e  ffer with zeros.
87a0: 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20    A VFS that.** 
87b0: 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69  fails to zero-fi
87c0: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d  ll short reads m
87d0: 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72  ight seem to wor
87e0: 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  k.  However,.** 
87f0: 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d  failure to zero-
8800: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8810: 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
8820: 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61   lead to.** data
8830: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e  base corruption.
8840: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
8850: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8860: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f  thods sqlite3_io
8870: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
8880: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
8890: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ods {.  int iVer
88a0: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
88b0: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69  lose)(sqlite3_fi
88c0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  le*);.  int (*xR
88d0: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ead)(sqlite3_fil
88e0: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  e*, void*, int i
88f0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8900: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8910: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
8920: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
8930: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8940: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8950: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8960: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
8970: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
8980: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
8990: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
89a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
89b0: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
89c0: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
89d0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
89e0: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b  3_int64 *pSize);
89f0: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28  .  int (*xLock)(
8a00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8a10: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  nt);.  int (*xUn
8a20: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  lock)(sqlite3_fi
8a30: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8a40: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65   (*xCheckReserve
8a50: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  dLock)(sqlite3_f
8a60: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f  ile*, int *pResO
8a70: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ut);.  int (*xFi
8a80: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
8a90: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
8aa0: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
8ab0: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
8ac0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
8ad0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
8ae0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8af0: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
8b00: 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *);.  /* Methods
8b10: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
8b20: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a   for version 1 *
8b30: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61  /.  int (*xShmMa
8b40: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8b50: 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70  , int iPg, int p
8b60: 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76  gsz, int, void v
8b70: 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e  olatile**);.  in
8b80: 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71  t (*xShmLock)(sq
8b90: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8ba0: 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20   offset, int n, 
8bb0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f  int flags);.  vo
8bc0: 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72  id (*xShmBarrier
8bd0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8be0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e  ;.  int (*xShmUn
8bf0: 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  map)(sqlite3_fil
8c00: 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c  e*, int deleteFl
8c10: 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  ag);.  /* Method
8c20: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
8c30: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20  d for version 2 
8c40: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63  */.  int (*xFetc
8c50: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
8c60: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8c70: 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c  iOfst, int iAmt,
8c80: 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69   void **pp);.  i
8c90: 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73  nt (*xUnfetch)(s
8ca0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8cb0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8cc0: 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f  t, void *p);.  /
8cd0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8ce0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8cf0: 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20  rsion 3 */.  /* 
8d00: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
8d10: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
8d20: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
8d30: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
8d40: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
8d50: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
8d60: 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  Opcodes.** KEYWO
8d70: 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72  RDS: {file contr
8d80: 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c  ol opcodes} {fil
8d90: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8da0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  }.**.** These in
8db0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
8dc0: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
8dd0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8de0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
8df0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
8e00: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
8e10: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
8e20: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8e30: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
8e40: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
8e50: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8e60: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a  L_LOCKSTATE]].**
8e70: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8e80: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
8e90: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
8ea0: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
8eb0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
8ec0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
8ed0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
8ee0: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
8ef0: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
8f00: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
8f10: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
8f20: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
8f30: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
8f40: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
8f50: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
8f60: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
8f70: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
8f80: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
8f90: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
8fa0: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
8fb0: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
8fc0: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
8fd0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
8fe0: 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20  ing and is only 
8ff0: 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e 20 74  available when t
9000: 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  he SQLITE_TEST.*
9010: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
9020: 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
9030: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9040: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
9050: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
9060: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
9070: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
9080: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
9090: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
90a0: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
90b0: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
90c0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
90d0: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
90e0: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
90f0: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
9100: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
9110: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
9120: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
9130: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
9140: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
9150: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
9160: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
9170: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
9180: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
9190: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
91a0: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
91b0: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
91c0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
91d0: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
91e0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
91f0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d  NTL_CHUNK_SIZE]]
9200: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9210: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
9220: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9230: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
9240: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
9250: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
9260: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
9270: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
9280: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
9290: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
92a0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
92b0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
92c0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
92d0: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
92e0: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
92f0: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
9300: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
9310: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
9320: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
9330: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
9340: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
9350: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
9360: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
9370: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
9380: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
9390: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
93a0: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
93b0: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
93c0: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
93d0: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ystems..**.** <l
93e0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
93f0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a  _FILE_POINTER]].
9400: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9410: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9420: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
9430: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
9440: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
9450: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9460: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9470: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
9480: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
9490: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
94a0: 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  also [SQLITE_FCN
94b0: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
94c0: 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ER]..**.** <li>[
94d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f  [SQLITE_FCNTL_JO
94e0: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a  URNAL_POINTER]].
94f0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9500: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
9510: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
9520: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
9530: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
9540: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9550: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
9560: 74 65 64 20 77 69 74 68 20 74 68 65 20 6a 6f 75  ted with the jou
9570: 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74 68 65  rnal file (eithe
9580: 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61  r.** the [rollba
9590: 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74  ck journal] or t
95a0: 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61 64 20  he [write-ahead 
95b0: 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61 72 74  log]) for a part
95c0: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
95d0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
95e0: 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45  See also [SQLITE
95f0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9600: 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  TER]..**.** <li>
9610: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
9620: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a  YNC_OMITTED]].**
9630: 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73   No longer in us
9640: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
9650: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9660: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9670: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70  E_FCNTL_SYNC] op
9680: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
9690: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
96a0: 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65  SQLite and.** se
96b0: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d  nt to the VFS im
96c0: 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65  mediately before
96d0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
96e0: 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  d is invoked on 
96f0: 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69  a.** database fi
9700: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f  le descriptor. O
9710: 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 20  r, if the xSync 
9720: 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e  method is not in
9730: 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73  voked .** becaus
9740: 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20 63  e the user has c
9750: 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 65  onfigured SQLite
9760: 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d   with .** [PRAGM
9770: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
9780: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
9790: 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e  us=OFF] it is in
97a0: 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a  voked in place .
97b0: 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20  ** of the xSync 
97c0: 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20  method. In most 
97d0: 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74  cases, the point
97e0: 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  er argument pass
97f0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20  ed with.** this 
9800: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
9810: 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69  NULL. However, i
9820: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
9830: 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e  ile is being syn
9840: 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  ced.** as part o
9850: 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61  f a multi-databa
9860: 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61  se commit, the a
9870: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
9880: 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  o a nul-terminat
9890: 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ed.** string con
98a0: 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e  taining the tran
98b0: 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d  sactions master-
98c0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d  journal file nam
98d0: 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a  e. VFSes that .*
98e0: 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  * do not need th
98f0: 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64  is signal should
9900: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
9910: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
9920: 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73  plications .** s
9930: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b  hould not call [
9940: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9950: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
9960: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
9970: 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73  g so may .** dis
9980: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69  rupt the operati
9990: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
99a0: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
99b0: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
99c0: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
99d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
99e0: 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20  T_PHASETWO]].** 
99f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9a00: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
9a10: 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  O] opcode is gen
9a20: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
9a30: 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  y by SQLite.** a
9a40: 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  nd sent to the V
9a50: 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e 73  FS after a trans
9a60: 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20  action has been 
9a70: 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69  committed immedi
9a80: 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66  ately.** but bef
9a90: 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ore the database
9aa0: 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46   is unlocked. VF
9ab0: 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  Ses that do not 
9ac0: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
9ad0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  .** should silen
9ae0: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
9af0: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
9b00: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
9b10: 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
9b20: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9b30: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
9b40: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
9b50: 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a  y disrupt the .*
9b60: 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  * operation of t
9b70: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
9b80: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
9b90: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
9ba0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9bb0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
9bc0: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
9bd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
9be0: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
9bf0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
9c00: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
9c10: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
9c20: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
9c30: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
9c40: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
9c50: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
9c60: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
9c70: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
9c80: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
9c90: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
9ca0: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
9cb0: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
9cc0: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
9cd0: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
9ce0: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
9cf0: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
9d00: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
9d10: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
9d20: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
9d30: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
9d40: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
9d50: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
9d60: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
9d70: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
9d80: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
9d90: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
9da0: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
9db0: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
9dc0: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
9dd0: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
9de0: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
9df0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
9e00: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
9e10: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
9e20: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
9e30: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
9e40: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
9e50: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
9e60: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
9e70: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
9e80: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
9e90: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
9ea0: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
9eb0: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
9ec0: 73 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  s the new retry 
9ed0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
9ee0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9ef0: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9f00: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9f10: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9f20: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9f30: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9f40: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9f50: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9f60: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9f70: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9f80: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9f90: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9fa0: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9fb0: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9fc0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9fd0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9fe0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9ff0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a000: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
a010: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
a020: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
a030: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
a040: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
a050: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
a060: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
a070: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
a080: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
a090: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
a0a0: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
a0b0: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
a0c0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
a0d0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
a0e0: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
a0f0: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
a100: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
a110: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
a120: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
a130: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
a140: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
a150: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
a160: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
a170: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
a180: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
a190: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
a1a0: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
a1b0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
a1c0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
a1d0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
a1e0: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
a1f0: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
a200: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
a210: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
a220: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
a230: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
a240: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
a250: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
a260: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
a270: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
a280: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
a290: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
a2a0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
a2b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a2c0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
a2d0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
a2e0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
a2f0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
a300: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
a310: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
a320: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
a330: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
a340: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
a350: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a360: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a370: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a380: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a390: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
a3a0: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
a3b0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a3c0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a3d0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
a3e0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a3f0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a400: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a410: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a420: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a430: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
a440: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
a450: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
a460: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
a470: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
a480: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
a490: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
a4a0: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
a4b0: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
a4c0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
a4d0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
a4e0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a4f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a500: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a510: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a520: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a530: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a540: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a550: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a560: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a570: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a580: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a590: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a5a0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a5b0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a5c0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a5d0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a5e0: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a5f0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a600: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a610: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a620: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a630: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a640: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a650: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a660: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a670: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a680: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a690: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a6a0: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a6b0: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a6c0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a6d0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a6e0: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a6f0: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a700: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a710: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a720: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a730: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a740: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a750: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a760: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a770: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a780: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a790: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a7a0: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a7b0: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a7c0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a7d0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a7e0: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a7f0: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a800: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a810: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a820: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a830: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a840: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a850: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a860: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a870: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a880: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a890: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a8a0: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a8b0: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a8c0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a8d0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a8e0: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a8f0: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a900: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a910: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a920: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a930: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a940: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a950: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a960: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a970: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a980: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a990: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a9a0: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a9b0: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a9c0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a9d0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a9e0: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a9f0: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
aa00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
aa10: 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e  S_POINTER]].** ^
aa20: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
aa30: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f  L_VFS_POINTER] o
aa40: 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70 6f  pcode finds a po
aa50: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
aa60: 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73  -level.** [VFSes
aa70: 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75  ] currently in u
aa80: 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d  se.  ^(The argum
aa90: 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69  ent X in.** sqli
aaa0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
aab0: 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c  (db,SQLITE_FCNTL
aac0: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20  _VFS_POINTER,X) 
aad0: 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79  must be.** of ty
aae0: 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66 73  pe "[sqlite3_vfs
aaf0: 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70 63  ] **".  This opc
ab00: 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a 58  odes will set *X
ab10: 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65 72  .** to a pointer
ab20: 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65   to the top-leve
ab30: 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65  l VFS.)^.** ^Whe
ab40: 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c 74  n there are mult
ab50: 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20 69  iple VFS shims i
ab60: 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68 69  n the stack, thi
ab70: 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 74  s opcode finds t
ab80: 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74  he.** upper-most
ab90: 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a   shim only..**.*
aba0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
abb0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a  CNTL_PRAGMA]].**
abc0: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52   ^Whenever a [PR
abd0: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20  AGMA] statement 
abe0: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53  is parsed, an [S
abf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ac00: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  MA] .** file con
ac10: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20  trol is sent to 
ac20: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65  the open [sqlite
ac30: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63  3_file] object c
ac40: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
ac50: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
ac60: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68  file to which th
ac70: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  e pragma stateme
ac80: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20  nt refers. ^The 
ac90: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
aca0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
acb0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
acc0: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61  ntrol is an arra
acd0: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73  y of.** pointers
ace0: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61   to strings (cha
acf0: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68  r**) in which th
ad00: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74  e second element
ad10: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a   of the array.**
ad20: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
ad30: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74  the pragma and t
ad40: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74  he third element
ad50: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
ad60: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d   to the.** pragm
ad70: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  a or NULL if the
ad80: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61   pragma has no a
ad90: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68  rgument.  ^The h
ada0: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a  andler for an.**
adb0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
adc0: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
add0: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c  rol can optional
ade0: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73  ly make the firs
adf0: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20  t element.** of 
ae00: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d  the char** argum
ae10: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  ent point to a s
ae20: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
ae30: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
ae40: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68  intf()].** or th
ae50: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64  e equivalent and
ae60: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c   that string wil
ae70: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73  l become the res
ae80: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ult of the pragm
ae90: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f  a or.** the erro
aea0: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65  r message if the
aeb0: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e   pragma fails. ^
aec0: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
aed0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
aee0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
aef0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  urns [SQLITE_NOT
af00: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72  FOUND], then nor
af10: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d  mal .** [PRAGMA]
af20: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74   processing cont
af30: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20  inues.  ^If the 
af40: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
af50: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
af60: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
af70: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20  QLITE_OK], then 
af80: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d  the parser assum
af90: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56  es that the.** V
afa0: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74  FS has handled t
afb0: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66  he PRAGMA itself
afc0: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20   and the parser 
afd0: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f  generates a no-o
afe0: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  p.** prepared st
aff0: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c  atement if resul
b000: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c  t string is NULL
b010: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e  , or that return
b020: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
b030: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  he result string
b040: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   if the string i
b050: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e  s non-NULL..** ^
b060: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
b070: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
b080: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
b090: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20  s.** any result 
b0a0: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20  code other than 
b0b0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b  [SQLITE_OK] or [
b0c0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
b0d0: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
b0e0: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63  that the VFS enc
b0f0: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f  ountered an erro
b100: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67  r while handling
b110: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e   the [PRAGMA] an
b120: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61  d the.** compila
b130: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47  tion of the PRAG
b140: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  MA fails with an
b150: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53   error.  ^The [S
b160: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b170: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
b180: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68  rol occurs at th
b190: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70  e beginning of p
b1a0: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
b1b0: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a  analysis and so.
b1c0: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f  ** it is able to
b1d0: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d   override built-
b1e0: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74  in [PRAGMA] stat
b1f0: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ements..**.** <l
b200: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b210: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a  _BUSYHANDLER]].*
b220: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
b230: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b240: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  ].** file-contro
b250: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  l may be invoked
b260: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68   by SQLite on th
b270: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
b280: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c  handle.** shortl
b290: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70  y after it is op
b2a0: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  ened in order to
b2b0: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f   provide a custo
b2c0: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73  m VFS with acces
b2d0: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e  s.** to the conn
b2e0: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e  ections busy-han
b2f0: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54  dler callback. T
b300: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  he argument is o
b310: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29  f type (void **)
b320: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f  .** - an array o
b330: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76  f two (void *) v
b340: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74  alues. The first
b350: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c   (void *) actual
b360: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20  ly points.** to 
b370: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
b380: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64  pe (int (*)(void
b390: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74   *)). In order t
b3a0: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e  o invoke the con
b3b0: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79  nections.** busy
b3c0: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66  -handler, this f
b3d0: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  unction should b
b3e0: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
b3f0: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20  he second (void 
b400: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72  *) in.** the arr
b410: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61  ay as the only a
b420: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72  rgument. If it r
b430: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
b440: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74   then the operat
b450: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
b460: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20   retried. If it 
b470: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
b480: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f  e custom VFS sho
b490: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a  uld abandon the.
b4a0: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  ** current opera
b4b0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
b4c0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b4d0: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a  EMPFILENAME]].**
b4e0: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61   ^Application ca
b4f0: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51  n invoke the [SQ
b500: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b510: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f  ILENAME] file-co
b520: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65  ntrol.** to have
b530: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65   SQLite generate
b540: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20   a.** temporary 
b550: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74  filename using t
b560: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
b570: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77  m that is follow
b580: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a  ed to generate.*
b590: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b5a0: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74  names for TEMP t
b5b0: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20  ables and other 
b5c0: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20  internal uses.  
b5d0: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  The.** argument 
b5e0: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72  should be a char
b5f0: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
b600: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
b610: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69   filename.** wri
b620: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
b630: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
b640: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
b650: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73  ].  The caller s
b660: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20  hould.** invoke 
b670: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
b680: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74   on the result t
b690: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79  o avoid a memory
b6a0: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   leak..**.** <li
b6b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b6c0: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  MMAP_SIZE]].** T
b6d0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b6e0: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
b6f0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b700: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74   to query or set
b710: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20   the.** maximum 
b720: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
b730: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65  that will be use
b740: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70  d for memory-map
b750: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20  ped I/O..** The 
b760: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
b770: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65  inter to a value
b780: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33   of type sqlite3
b790: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69  _int64 that.** i
b7a0: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61  s an advisory ma
b7b0: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b7c0: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
b7d0: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e  e to memory map.
b7e0: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72    The.** pointer
b7f0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
b800: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c  with the old val
b810: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69  ue.  The limit i
b820: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66  s not changed if
b830: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72  .** the value or
b840: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64  iginally pointed
b850: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c   to is negative,
b860: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72   and so the curr
b870: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61  ent limit .** ca
b880: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20  n be queried by 
b890: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69  passing in a poi
b8a0: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69  nter to a negati
b8b0: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73  ve number.  This
b8c0: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
b8d0: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
b8e0: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  lly to implement
b8f0: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
b900: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ze]..**.** <li>[
b910: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
b920: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ACE]].** The [SQ
b930: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
b940: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70  ] file control p
b950: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79  rovides advisory
b960: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
b970: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74  to the VFS about
b980: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72   what the higher
b990: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53   layers of the S
b9a0: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20  QLite stack are 
b9b0: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66  doing..** This f
b9c0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
b9d0: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20  sed by some VFS 
b9e0: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67  activity tracing
b9f0: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65   [shims]..** The
ba00: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a   argument is a z
ba10: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
ba20: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c  tring.  Higher l
ba30: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  ayers in the.** 
ba40: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79  SQLite stack may
ba50: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e   generate instan
ba60: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ces of this file
ba70: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74   control if.** t
ba80: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46  he [SQLITE_USE_F
ba90: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70  CNTL_TRACE] comp
baa0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
bab0: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
bac0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bad0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d  CNTL_HAS_MOVED]]
bae0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
baf0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
bb00: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e   file control in
bb10: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
bb20: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f  ument as a.** po
bb30: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
bb40: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65  ger and it write
bb50: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f  s a boolean into
bb60: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65   that integer de
bb70: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68  pending.** on wh
bb80: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
bb90: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72   file has been r
bba0: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f  enamed, moved, o
bbb0: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20  r deleted since 
bbc0: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20  it.** was first 
bbd0: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opened..**.** <l
bbe0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bbf0: 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c  _WIN32_GET_HANDL
bc00: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
bc10: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47  TE_FCNTL_WIN32_G
bc20: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
bc30: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
bc40: 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a 20 75   obtain the.** u
bc50: 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69 76 65  nderlying native
bc60: 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 73 73   file handle ass
bc70: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 66  ociated with a f
bc80: 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54 68 69  ile handle.  Thi
bc90: 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f  s file.** contro
bca0: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
bcb0: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 20 70   argument as a p
bcc0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61 74 69  ointer to a nati
bcd0: 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61  ve file handle a
bce0: 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74 68 65  nd.** writes the
bcf0: 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c 75 65   resulting value
bd00: 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c   there..**.** <l
bd10: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bd20: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
bd30: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
bd40: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
bd50: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
bd60: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
bd70: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
bd80: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
bd90: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
bda0: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20   method to swap 
bdb0: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  the file handle 
bdc0: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20  with the one.** 
bdd0: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
bde0: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e  e pArg argument.
bdf0: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74    This capabilit
be00: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  y is used during
be10: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20   testing.** and 
be20: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
be30: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
be40: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64  SQLITE_TEST is d
be50: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  efined..**.** <l
be60: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
be70: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20  _WAL_BLOCK]].** 
be80: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
be90: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20  L_WAL_BLOCK] is 
bea0: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20  a signal to the 
beb0: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69  VFS layer that i
bec0: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64  t might.** be ad
bed0: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c  vantageous to bl
bee0: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20  ock on the next 
bef0: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20  WAL lock if the 
bf00: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65  lock is not imme
bf10: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c  diately.** avail
bf20: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73  able.  The WAL s
bf30: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20  ubsystem issues 
bf40: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69  this signal duri
bf50: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75  ng rare.** circu
bf60: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65  mstances in orde
bf70: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c  r to fix a probl
bf80: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79  em with priority
bf90: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41   inversion..** A
bfa0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
bfb0: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  ld <em>not</em> 
bfc0: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  use this file-co
bfd0: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ntrol..**.** <li
bfe0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bff0: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20  ZIPVFS]].** The 
c000: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49  [SQLITE_FCNTL_ZI
c010: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20  PVFS] opcode is 
c020: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a  implemented by z
c030: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20  ipvfs only. All 
c040: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f  other.** VFS sho
c050: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
c060: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74  E_NOTFOUND for t
c070: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a  his opcode..**.*
c080: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c090: 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68  CNTL_RBU]].** Th
c0a0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c0b0: 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  RBU] opcode is i
c0c0: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68  mplemented by th
c0d0: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73  e special VFS us
c0e0: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55  ed by.** the RBU
c0f0: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e   extension only.
c100: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20    All other VFS 
c110: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
c120: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
c130: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65  r.** this opcode
c140: 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  .  .** </ul>.*/.
c150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c160: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
c170: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
c180: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c190: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
c1a0: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64  YFILE       2.#d
c1b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c1c0: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
c1d0: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65  FILE       3.#de
c1e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c1f0: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  L_LAST_ERRNO    
c200: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
c210: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c220: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
c230: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
c240: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c250: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
c260: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
c270: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
c280: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
c290: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
c2a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
c2b0: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20  NC_OMITTED      
c2c0: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
c2d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c2e0: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20  32_AV_RETRY     
c2f0: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
c300: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
c310: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20  IST_WAL         
c320: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
c330: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
c340: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
c350: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    11.#define SQL
c360: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
c370: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
c380: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
c390: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
c3a0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
c3b0: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
c3c0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20  E_FCNTL_PRAGMA  
c3d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
c3e0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
c3f0: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
c400: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35  ER            15
c410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c420: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
c430: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a  ME           16.
c440: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c450: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  CNTL_MMAP_SIZE  
c460: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23              18.#
c470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c480: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20  NTL_TRACE       
c490: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64             19.#d
c4a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c4b0: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20  TL_HAS_MOVED    
c4c0: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65            20.#de
c4d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c4e0: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  L_SYNC          
c4f0: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66           21.#def
c500: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c510: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
c520: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69          22.#defi
c530: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c540: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
c550: 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e         23.#defin
c560: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
c570: 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20  AL_BLOCK        
c580: 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65        24.#define
c590: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49   SQLITE_FCNTL_ZI
c5a0: 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20  PVFS            
c5b0: 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20       25.#define 
c5c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55  SQLITE_FCNTL_RBU
c5d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c5e0: 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53      26.#define S
c5f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f  QLITE_FCNTL_VFS_
c600: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
c610: 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51     27.#define SQ
c620: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
c630: 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  AL_POINTER      
c640: 20 20 32 38 0a 23 64 65 66 69 6e 65 20 53 51 4c    28.#define SQL
c650: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
c660: 47 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20  GET_HANDLE      
c670: 20 32 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   29.#define SQLI
c680: 54 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20 20  TE_FCNTL_PDB    
c690: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c6a0: 33 30 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74 65  30../* deprecate
c6b0: 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69  d names */.#defi
c6c0: 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f  ne SQLITE_GET_LO
c6d0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
c6e0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45   SQLITE_FCNTL_GE
c6f0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a  T_LOCKPROXYFILE.
c700: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
c710: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c720: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
c730: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
c740: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c  FILE.#define SQL
c750: 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20  ITE_LAST_ERRNO  
c760: 20 20 20 20 20 20 20 20 20 20 20 53 51 4c 49 54             SQLIT
c770: 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52  E_FCNTL_LAST_ERR
c780: 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  NO.../*.** CAPI3
c790: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c  REF: Mutex Handl
c7a0: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65  e.**.** The mute
c7b0: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20  x module within 
c7c0: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b  SQLite defines [
c7d0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74  sqlite3_mutex] t
c7e0: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72  o be an.** abstr
c7f0: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d  act type for a m
c800: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68  utex object.  Th
c810: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65  e SQLite core ne
c820: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20  ver looks.** at 
c830: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
c840: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  resentation of a
c850: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  n [sqlite3_mutex
c860: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64  ].  It only.** d
c870: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65  eals with pointe
c880: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  rs to the [sqlit
c890: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
c8a0: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20  ..**.** Mutexes 
c8b0: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
c8c0: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
c8d0: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79  _alloc()]..*/.ty
c8e0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
c8f0: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74  ite3_mutex sqlit
c900: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a  e3_mutex;../*.**
c910: 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 61   CAPI3REF: Loada
c920: 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 54 68  ble Extension Th
c930: 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e  unk.**.** A poin
c940: 74 65 72 20 74 6f 20 74 68 65 20 6f 70 61 71 75  ter to the opaqu
c950: 65 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f  e sqlite3_api_ro
c960: 75 74 69 6e 65 73 20 73 74 72 75 63 74 75 72 65  utines structure
c970: 20 69 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a   is passed as.**
c980: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
c990: 65 74 65 72 20 74 6f 20 65 6e 74 72 79 20 70 6f  eter to entry po
c9a0: 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62 6c  ints of [loadabl
c9b0: 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 20  e extensions].  
c9c0: 54 68 69 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  This.** structur
c9d0: 65 20 6d 75 73 74 20 62 65 20 74 79 70 65 64 65  e must be typede
c9e0: 66 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  fed in order to 
c9f0: 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d 70  work around comp
ca00: 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a 2a  iler warnings.**
ca10: 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f 72   on some platfor
ca20: 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ms..*/.typedef s
ca30: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61 70  truct sqlite3_ap
ca40: 69 5f 72 6f 75 74 69 6e 65 73 20 73 71 6c 69 74  i_routines sqlit
ca50: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 3b  e3_api_routines;
ca60: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
ca70: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
ca80: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  bject.**.** An i
ca90: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73  nstance of the s
caa0: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
cab0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
cac0: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a  terface between.
cad0: 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  ** the SQLite co
cae0: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72  re and the under
caf0: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
cb00: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66  system.  The "vf
cb10: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d  s".** in the nam
cb20: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20  e of the object 
cb30: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74  stands for "virt
cb40: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22  ual file system"
cb50: 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56  .  See.** the [V
cb60: 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e  FS | VFS documen
cb70: 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74  tation] for furt
cb80: 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  her information.
cb90: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  .**.** The value
cba0: 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   of the iVersion
cbb0: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61   field is initia
cbc0: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65  lly 1 but may be
cbd0: 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75   larger in.** fu
cbe0: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
cbf0: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69   SQLite.  Additi
cc00: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20  onal fields may 
cc10: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
cc20: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68  his.** object wh
cc30: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  en the iVersion 
cc40: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73  value is increas
cc50: 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  ed.  Note that t
cc60: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  he structure.** 
cc70: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
cc80: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65  fs object change
cc90: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63  s in the transac
cca0: 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  tion between.** 
ccb0: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
ccc0: 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61  .5.9 and 3.6.0 a
ccd0: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
cce0: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
ccf0: 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a  t.** modified..*
cd00: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
cd10: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
cd20: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
cd30: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
cd40: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
cd50: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
cd60: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
cd70: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
cd80: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
cd90: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
cda0: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
cdb0: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
cdc0: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
cdd0: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
cde0: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
cdf0: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
ce00: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
ce10: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
ce20: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
ce30: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
ce40: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
ce50: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
ce60: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
ce70: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
ce80: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
ce90: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
cea0: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
ceb0: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61  .  Neither the a
cec0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
ced0: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69  nor the VFS.** i
cee0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
cef0: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65  ould use the pNe
cf00: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  xt pointer..**.*
cf10: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
cf20: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
cf30: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  eld in the sqlit
cf40: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74  e3_vfs.** struct
cf50: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
cf60: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
cf70: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
cf80: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
cf90: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
cfa0: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
cfb0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
cfc0: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
cfd0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
cfe0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
cff0: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
d000: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
d010: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
d020: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
d030: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
d040: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
d050: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
d060: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
d070: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
d080: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
d090: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
d0a0: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
d0b0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
d0c0: 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51  s.xOpen]].** ^SQ
d0d0: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
d0e0: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
d0f0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
d100: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
d110: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
d120: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
d130: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
d140: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74  llPathname() wit
d150: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75  h an optional su
d160: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e  ffix added..** ^
d170: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61  If a suffix is a
d180: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c  dded to the zFil
d190: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c  ename parameter,
d1a0: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73   it will.** cons
d1b0: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  ist of a single 
d1c0: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f  "-" character fo
d1d0: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72  llowed by no mor
d1e0: 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70  e than.** 11 alp
d1f0: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72  hanumeric and/or
d200: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e   "-" characters.
d210: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74  .** ^SQLite furt
d220: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
d230: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
d240: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
d250: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
d260: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
d270: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
d280: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
d290: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20  us sentence,.** 
d2a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
d2b0: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
d2c0: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
d2d0: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
d2e0: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
d2f0: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
d300: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
d310: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
d320: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
d330: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73  eter to xOpen is
d340: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
d350: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
d360: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77  st invent its ow
d370: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
d380: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
d390: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a  ^Whenever the .*
d3a0: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
d3b0: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
d3c0: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
d3d0: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
d3e0: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
d3f0: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
d400: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
d410: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
d420: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
d430: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
d440: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
d450: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
d460: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
d470: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
d480: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
d490: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
d4a0: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
d4b0: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
d4c0: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
d4d0: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
d4e0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
d4f0: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
d500: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
d510: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
d520: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
d530: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
d540: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
d550: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
d560: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
d570: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
d580: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
d590: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
d5a0: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20  * ^(SQLite will 
d5b0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
d5c0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
d5d0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
d5e0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
d5f0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
d600: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
d610: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
d620: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d630: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
d640: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d650: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
d660: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d670: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
d680: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d690: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
d6a0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
d6b0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
d6c0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
d6d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
d6e0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
d6f0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
d700: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
d710: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d720: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75  OPEN_WAL].** </u
d730: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  l>)^.**.** The f
d740: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
d750: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
d760: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
d770: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
d780: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
d790: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
d7a0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
d7b0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
d7c0: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
d7d0: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
d7e0: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
d7f0: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
d800: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
d810: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
d820: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
d830: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
d840: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
d850: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
d860: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
d870: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
d880: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
d890: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
d8a0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
d8b0: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
d8c0: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
d8d0: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
d8e0: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
d8f0: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
d900: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
d910: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
d920: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
d930: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
d940: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
d950: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
d960: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
d970: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
d980: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
d990: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
d9a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
d9b0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
d9c0: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
d9d0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
d9e0: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
d9f0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
da00: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
da10: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
da20: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
da30: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
da40: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
da50: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
da60: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
da70: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
da80: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73  for TEMP databas
da90: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75  es and their jou
daa0: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74  rnals, transient
dab0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61  .** databases, a
dac0: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a  nd subjournals..
dad0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
dae0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
daf0: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79  E] flag is alway
db00: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e  s used in conjun
db10: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
db20: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
db30: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69  REATE] flag, whi
db40: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65  ch are both dire
db50: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75  ctly.** analogou
db60: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20  s to the O_EXCL 
db70: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67  and O_CREAT flag
db80: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f  s of the POSIX o
db90: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54  pen().** API.  T
dba0: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  he SQLITE_OPEN_E
dbb0: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77  XCLUSIVE flag, w
dbc0: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20  hen paired with 
dbd0: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  the .** SQLITE_O
dbe0: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75  PEN_CREATE, is u
dbf0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
dc00: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64  that file should
dc10: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72   always.** be cr
dc20: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20  eated, and that 
dc30: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69  it is an error i
dc40: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69  f it already exi
dc50: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69  sts..** It is <i
dc60: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f  >not</i> used to
dc70: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69   indicate the fi
dc80: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
dc90: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c  ned .** for excl
dca0: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a  usive access..**
dcb0: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a  .** ^At least sz
dcc0: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
dcd0: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
dce0: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
dcf0: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
dd00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
dd10: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
dd20: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
dd30: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
dd40: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  .  The xOpen met
dd50: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
dd60: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
dd70: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
dd80: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
dd90: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65  ill it in.  Note
dda0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70   that.** the xOp
ddb0: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73  en method must s
ddc0: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
ddd0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20  ile.pMethods to 
dde0: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69  either.** a vali
ddf0: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  d [sqlite3_io_me
de00: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72  thods] object or
de10: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e   to NULL.  xOpen
de20: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73   must do.** this
de30: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65   even if the ope
de40: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65  n fails.  SQLite
de50: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68   expects that th
de60: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
de70: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65  Methods.** eleme
de80: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  nt will be valid
de90: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74   after xOpen ret
dea0: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20  urns regardless 
deb0: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a  of the success.*
dec0: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  * or failure of 
ded0: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a  the xOpen call..
dee0: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
def0: 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a  vfs.xAccess]].**
df00: 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75   ^The flags argu
df10: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
df20: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
df30: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
df40: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
df50: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
df60: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
df70: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
df80: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
df90: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
dfa0: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
dfb0: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
dfc0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
dfd0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
dfe0: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
dff0: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
e000: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20     The file can 
e010: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72  be a.** director
e020: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  y..**.** ^SQLite
e030: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
e040: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
e050: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
e060: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
e070: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
e080: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
e090: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
e0a0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
e0b0: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
e0c0: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
e0d0: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
e0e0: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
e0f0: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
e100: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
e110: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
e120: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
e130: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
e140: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
e150: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
e160: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
e170: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
e180: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
e190: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
e1a0: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
e1b0: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
e1c0: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
e1d0: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
e1e0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
e1f0: 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e  Sleep(), xCurren
e200: 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75  tTime(), and xCu
e210: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
e220: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
e230: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  re not strictly 
e240: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69  a part of the fi
e250: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68  lesystem, but th
e260: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64  ey are.** includ
e270: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  ed in the VFS st
e280: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70  ructure for comp
e290: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65  leteness..** The
e2a0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66   xRandomness() f
e2b0: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73  unction attempts
e2c0: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65   to return nByte
e2d0: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f  s bytes.** of go
e2e0: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f  od-quality rando
e2f0: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e  mness into zOut.
e300: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c    The return val
e310: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74  ue is.** the act
e320: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  ual number of by
e330: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
e340: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54  s obtained..** T
e350: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
e360: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
e370: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
e380: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
e390: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
e3a0: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
e3b0: 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43   given.  ^The xC
e3c0: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
e3d0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
e3e0: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
e3f0: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
e400: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
e410: 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e   as.** a floatin
e420: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a  g point value..*
e430: 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54  * ^The xCurrentT
e440: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
e450: 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e  d returns, as an
e460: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75   integer, the Ju
e470: 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62  lian.** Day Numb
e480: 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79  er multiplied by
e490: 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e   86400000 (the n
e4a0: 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
e4b0: 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32  conds in .** a 2
e4c0: 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a  4-hour day).  .*
e4d0: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
e4e0: 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54  se the xCurrentT
e4f0: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
e500: 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72  d to get the cur
e510: 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64  rent.** date and
e520: 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65   time if that me
e530: 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c  thod is availabl
e540: 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69  e (if iVersion i
e550: 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74  s 2 or .** great
e560: 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74  er and the funct
e570: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
e580: 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c  ot NULL) and wil
e590: 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74  l fall back.** t
e5a0: 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  o xCurrentTime()
e5b0: 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65   if xCurrentTime
e5c0: 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61  Int64() is unava
e5d0: 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ilable..**.** ^T
e5e0: 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c  he xSetSystemCal
e5f0: 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43  l(), xGetSystemC
e600: 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74  all(), and xNest
e610: 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74  SystemCall() int
e620: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
e630: 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53  ot used by the S
e640: 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65  QLite core.  The
e650: 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65  se optional inte
e660: 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
e670: 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56  ded.** by some V
e680: 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61  FSes to facilita
e690: 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68  te testing of th
e6a0: 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f  e VFS code. By o
e6b0: 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79  verriding .** sy
e6c0: 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20  stem calls with 
e6d0: 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20  functions under 
e6e0: 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74  its control, a t
e6f0: 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a  est program can.
e700: 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c  ** simulate faul
e710: 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e  ts and error con
e720: 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75  ditions that wou
e730: 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20  ld otherwise be 
e740: 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20  difficult.** or 
e750: 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e  impossible to in
e760: 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f  duce.  The set o
e770: 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74  f system calls t
e780: 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72  hat can be overr
e790: 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20  idden.** varies 
e7a0: 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20  from one VFS to 
e7b0: 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f  another, and fro
e7c0: 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66  m one version of
e7d0: 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f   the same VFS to
e7e0: 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41   the.** next.  A
e7f0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
e800: 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72   use these inter
e810: 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72  faces must be pr
e820: 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a  epared for any.*
e830: 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73  * or all of thes
e840: 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20  e interfaces to 
e850: 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74  be NULL or for t
e860: 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f  heir behavior to
e870: 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20   change.** from 
e880: 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
e890: 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  he next.  Applic
e8a0: 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20  ations must not 
e8b0: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73  attempt to acces
e8c0: 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73  s.** any of thes
e8d0: 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65  e methods if the
e8e0: 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65   iVersion of the
e8f0: 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61   VFS is less tha
e900: 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n 3..*/.typedef 
e910: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
e920: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
e930: 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
e940: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
e950: 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63  tr)(void);.struc
e960: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
e970: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
e980: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
e990: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
e9a0: 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c  number (currentl
e9b0: 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a  y 3) */.  int sz
e9c0: 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20  OsFile;         
e9d0: 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75     /* Size of su
e9e0: 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33  bclassed sqlite3
e9f0: 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d  _file */.  int m
ea00: 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20  xPathname;      
ea10: 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66      /* Maximum f
ea20: 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e  ile pathname len
ea30: 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  gth */.  sqlite3
ea40: 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20  _vfs *pNext;    
ea50: 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74    /* Next regist
ea60: 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f  ered VFS */.  co
ea70: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b  nst char *zName;
ea80: 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
ea90: 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66  f this virtual f
eaa0: 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20  ile system */.  
eab0: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
eac0: 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e           /* Poin
ead0: 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69  ter to applicati
eae0: 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61  on-specific data
eaf0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65   */.  int (*xOpe
eb00: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
eb10: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
eb20: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  me, sqlite3_file
eb30: 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
eb40: 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74    int flags, int
eb50: 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20   *pOutFlags);.  
eb60: 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73  int (*xDelete)(s
eb70: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
eb80: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
eb90: 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20  int syncDir);.  
eba0: 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73  int (*xAccess)(s
ebb0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ebc0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
ebd0: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
ebe0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
ebf0: 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29  (*xFullPathname)
ec00: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
ec10: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
ec20: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
ec30: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
ec40: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
ec50: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
ec60: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
ec70: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
ec80: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
ec90: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
eca0: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
ecb0: 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29  void (*(*xDlSym)
ecc0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f  (sqlite3_vfs*,vo
ecd0: 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  id*, const char 
ece0: 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29  *zSymbol))(void)
ecf0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
ed00: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
ed10: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
ed20: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
ed30: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
ed40: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
ed50: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
ed60: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
ed70: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
ed80: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
ed90: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
eda0: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
edb0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  e*);.  int (*xGe
edc0: 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69  tLastError)(sqli
edd0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63  te3_vfs*, int, c
ede0: 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  har *);.  /*.  *
edf0: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
ee00: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
ee10: 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69  on 1 of the sqli
ee20: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20  te_vfs object.  
ee30: 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  ** definition.  
ee40: 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f  Those that follo
ee50: 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76  w are added in v
ee60: 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65  ersion 2 or late
ee70: 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  r.  */.  int (*x
ee80: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
ee90: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
eea0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b  sqlite3_int64*);
eeb0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
eec0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
eed0: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61   in versions 1 a
eee0: 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69  nd 2 of the sqli
eef0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
ef00: 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20   ** Those below 
ef10: 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  are for version 
ef20: 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20  3 and greater.. 
ef30: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74   */.  int (*xSet
ef40: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
ef50: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
ef60: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
ef70: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
ef80: 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73  );.  sqlite3_sys
ef90: 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53  call_ptr (*xGetS
efa0: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
efb0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
efc0: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63  har *zName);.  c
efd0: 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65  onst char *(*xNe
efe0: 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  xtSystemCall)(sq
eff0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
f000: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
f010: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
f020: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
f030: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68  in versions 1 th
f040: 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73  rough 3 of the s
f050: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
f060: 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64  ..  ** New field
f070: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
f080: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
f090: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
f0a0: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
f0b0: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
f0c0: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
f0d0: 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f  ens. .  */.};../
f0e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
f0f0: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
f100: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
f110: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
f120: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
f130: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
f140: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
f150: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
f160: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
f170: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
f180: 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
f190: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
f1a0: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
f1b0: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
f1c0: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
f1d0: 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
f1e0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
f1f0: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
f200: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
f210: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
f220: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
f230: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
f240: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
f250: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
f260: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
f270: 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20  ether the named 
f280: 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74  directory is bot
f290: 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  h readable and w
f2a0: 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f  ritable.** (in o
f2b0: 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66  ther words, if f
f2c0: 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65  iles can be adde
f2d0: 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20  d, removed, and 
f2e0: 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a  renamed within.*
f2f0: 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29  * the directory)
f300: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
f310: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
f320: 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72   constant is cur
f330: 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79  rently used only
f340: 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70   by the.** [temp
f350: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
f360: 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68   pragma], though
f370: 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e   this could chan
f380: 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a  ge in a future.*
f390: 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  * release of SQL
f3a0: 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  ite..** With SQL
f3b0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c  ITE_ACCESS_READ,
f3c0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
f3d0: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
f3e0: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
f3f0: 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  s readable.  The
f400: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
f410: 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a  EAD constant is.
f420: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75  ** currently unu
f430: 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d  sed, though it m
f440: 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20  ight be used in 
f450: 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  a future release
f460: 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a   of.** SQLite..*
f470: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f480: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
f490: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
f4a0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
f4b0: 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20  ITE 1   /* Used 
f4c0: 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73  by PRAGMA temp_s
f4d0: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a  tore_directory *
f4e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f4f0: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
f500: 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20    2   /* Unused 
f510: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
f520: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
f530: 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d  e xShmLock VFS m
f540: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
f550: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
f560: 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76  nts define the v
f570: 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f  arious locking o
f580: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c  perations.** all
f590: 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d  owed by the xShm
f5a0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b  Lock method of [
f5b0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
f5c0: 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c  ds].  The.** fol
f5d0: 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f  lowing are the o
f5e0: 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e  nly legal combin
f5f0: 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20  ations of flags 
f600: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f  to the.** xShmLo
f610: 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  ck method:.**.**
f620: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
f630: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
f640: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
f650: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
f660: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
f670: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
f680: 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
f690: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
f6a0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
f6b0: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
f6c0: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
f6d0: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
f6e0: 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IVE.** </ul>.**.
f6f0: 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e  ** When unlockin
f700: 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52  g, the same SHAR
f710: 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  ED or EXCLUSIVE 
f720: 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70  flag must be sup
f730: 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20  plied as.** was 
f740: 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72  given on the cor
f750: 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e  responding lock.
f760: 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68    .**.** The xSh
f770: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e  mLock method can
f780: 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
f790: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
f7a0: 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65   SHARED or.** be
f7b0: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
f7c0: 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49  nd EXCLUSIVE.  I
f7d0: 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74  t cannot transit
f7e0: 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52  ion between SHAR
f7f0: 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53  ED.** and EXCLUS
f800: 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  IVE..*/.#define 
f810: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
f820: 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e  K       1.#defin
f830: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43  e SQLITE_SHM_LOC
f840: 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  K         2.#def
f850: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  ine SQLITE_SHM_S
f860: 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64  HARED       4.#d
f870: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
f880: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a  _EXCLUSIVE    8.
f890: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f8a0: 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63   Maximum xShmLoc
f8b0: 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68  k index.**.** Th
f8c0: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
f8d0: 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d on [sqlite3_io
f8e0: 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73  _methods] may us
f8f0: 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  e values.** betw
f900: 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75  een 0 and this u
f910: 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74  pper bound as it
f920: 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d  s "offset" argum
f930: 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ent..** The SQLi
f940: 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76  te core will nev
f950: 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  er attempt to ac
f960: 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65  quire or release
f970: 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69   a.** lock outsi
f980: 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65  de of this range
f990: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
f9a0: 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20  TE_SHM_NLOCK    
f9b0: 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41      8.../*.** CA
f9c0: 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69  PI3REF: Initiali
f9d0: 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ze The SQLite Li
f9e0: 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  brary.**.** ^The
f9f0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fa00: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e  ize() routine in
fa10: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a  itializes the.**
fa20: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
fa30: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
fa40: 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
fa50: 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
fa60: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
fa70: 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
fa80: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
fa90: 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54  itialize()..** T
faa0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
fab0: 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69  e designed to ai
fac0: 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69  d in process ini
fad0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a  tialization and.
fae0: 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65  ** shutdown on e
faf0: 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e  mbedded systems.
fb00: 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70    Workstation ap
fb10: 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67  plications using
fb20: 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61  .** SQLite norma
fb30: 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  lly do not need 
fb40: 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  to invoke either
fb50: 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
fb60: 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
fb70: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
fb80: 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
fb90: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
fba0: 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
fbb0: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
fbc0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fbd0: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
fbe0: 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
fbf0: 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
fc00: 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
fc10: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
fc20: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fc30: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
fc40: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
fc50: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
fc60: 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20  down().  ^(Only 
fc70: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
fc80: 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
fc90: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
fca0: 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
fcb0: 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
fcc0: 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
fcd0: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
fce0: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
fcf0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fd00: 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  n() is an "effec
fd10: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
fd20: 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
fd30: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
fd40: 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63  _shutdown() sinc
fd50: 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  e the last sqlit
fd60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
fd70: 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65    ^(Only.** an e
fd80: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f  ffective call to
fd90: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fda0: 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69  n() does any dei
fdb0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  nitialization..*
fdc0: 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69  * All other vali
fdd0: 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  d calls to sqlit
fde0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72  e3_shutdown() ar
fdf0: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
fe00: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  s.)^.**.** The s
fe10: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fe20: 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
fe30: 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74   threadsafe, but
fe40: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fe50: 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20  n().** is not.  
fe60: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
fe70: 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65  down() interface
fe80: 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61   must only be ca
fe90: 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73  lled from a.** s
fea0: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41  ingle thread.  A
feb0: 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  ll open [databas
fec0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d  e connections] m
fed0: 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e  ust be closed an
fee0: 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53  d all.** other S
fef0: 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20  QLite resources 
ff00: 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61  must be dealloca
ff10: 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76  ted prior to inv
ff20: 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  oking.** sqlite3
ff30: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a  _shutdown()..**.
ff40: 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74  ** Among other t
ff50: 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f  hings, ^sqlite3_
ff60: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c  initialize() wil
ff70: 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  l invoke.** sqli
ff80: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
ff90: 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69  Similarly, ^sqli
ffa0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
ffb0: 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71  * will invoke sq
ffc0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a  lite3_os_end()..
ffd0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
ffe0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fff0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
10000 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
10010 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66  uccess..** ^If f
10020 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20  or some reason, 
10030 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10040 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  ze() is unable t
10050 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20  o initialize.** 
10060 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72  the library (per
10070 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c  haps it is unabl
10080 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20  e to allocate a 
10090 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20  needed resource 
100a0 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74  such.** as a mut
100b0 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61  ex) it returns a
100c0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
100d0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
100e0 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  E_OK]..**.** ^Th
100f0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10100 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
10110 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
10120 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
10130 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
10140 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
10150 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
10160 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
10170 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
10180 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10190 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
101a0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
101b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
101c0 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
101d0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
101e0 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
101f0 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
10200 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
10210 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
10220 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
10230 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
10240 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
10250 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
10260 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53    ^However, if S
10270 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
10280 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  d with the [SQLI
10290 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
102a0 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ].** compile-tim
102b0 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
102c0 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
102d0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
102e0 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
102f0 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
10300 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
10310 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
10320 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
10330 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
10340 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
10350 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
10360 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
10370 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
10380 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
10390 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
103a0 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
103b0 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
103c0 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
103d0 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
103e0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
103f0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
10400 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
10410 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
10420 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
10430 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
10440 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
10450 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
10460 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
10470 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f  d with [SQLITE_O
10480 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69  MIT_AUTOINIT] mi
10490 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a  ght become the.*
104a0 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  * default behavi
104b0 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  or in some futur
104c0 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
104d0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite..**.** The s
104e0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
104f0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70   routine does op
10500 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
10510 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69  pecific.** initi
10520 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65  alization of the
10530 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
10540 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
10550 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  _end().** routin
10560 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
10570 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ect of sqlite3_o
10580 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63  s_init().  Typic
10590 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66  al tasks.** perf
105a0 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72  ormed by these r
105b0 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20  outines include 
105c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65  allocation or de
105d0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
105e0 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65   static resource
105f0 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  s, initializatio
10600 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69  n of global vari
10610 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e  ables,.** settin
10620 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b  g up a default [
10630 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64  sqlite3_vfs] mod
10640 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20  ule, or setting 
10650 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20  up.** a default 
10660 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73  configuration us
10670 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ing [sqlite3_con
10680 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  fig()]..**.** Th
10690 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
106a0 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b  ould never invok
106b0 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  e either sqlite3
106c0 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72  _os_init().** or
106d0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
106e0 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65  ) directly.  The
106f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
10700 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a  uld only invoke.
10710 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
10720 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69  alize() and sqli
10730 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
10740 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
10750 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66  init().** interf
10760 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75  ace is called au
10770 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
10780 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10790 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  e() and.** sqlit
107a0 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63  e3_os_end() is c
107b0 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33  alled by sqlite3
107c0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70  _shutdown().  Ap
107d0 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70  propriate.** imp
107e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
107f0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10800 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
10810 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62  s_end().** are b
10820 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
10830 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
10840 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57  iled for Unix, W
10850 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e  indows, or OS/2.
10860 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d  .** When [custom
10870 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20   builds | built 
10880 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f  for other platfo
10890 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74  rms].** (using t
108a0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  he [SQLITE_OS_OT
108b0 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74  HER=1] compile-t
108c0 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74  ime.** option) t
108d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
108e0 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69  ust supply a sui
108f0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
10900 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  tion for.** sqli
10910 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
10920 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
10930 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74  ().  An applicat
10940 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ion-supplied.** 
10950 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
10960 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
10970 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  t() or sqlite3_o
10980 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20  s_end().** must 
10990 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
109a0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
109b0 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72  d some other [er
109c0 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a  ror code] upon.*
109d0 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e  * failure..*/.in
109e0 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
109f0 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20  lize(void);.int 
10a00 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10a10 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
10a20 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64  te3_os_init(void
10a30 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
10a40 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
10a50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
10a60 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
10a70 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
10a80 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
10a90 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
10aa0 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
10ab0 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75  e global configu
10ac0 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
10ad0 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f  s to SQLite in o
10ae0 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c  rder to tune SQL
10af0 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69  ite to the speci
10b00 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20  fic needs of.** 
10b10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
10b20 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f    The default co
10b30 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72  nfiguration is r
10b40 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d  ecommended for m
10b50 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
10b60 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20  ons and so this 
10b70 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c  routine is usual
10b80 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  ly not necessary
10b90 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76  .  It is.** prov
10ba0 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ided to support 
10bb0 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  rare application
10bc0 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e  s with unusual n
10bd0 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54  eeds..**.** <b>T
10be0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
10bf0 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
10c00 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
10c10 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
10c20 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20  .** must ensure 
10c30 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
10c40 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
10c50 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
10c60 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
10c70 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
10c80 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
10c90 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  g.</b>.**.** The
10ca0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10cb0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d  ) interface.** m
10cc0 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
10cd0 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
10ce0 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
10cf0 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
10d00 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10d10 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
10d20 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
10d30 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
10d40 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
10d50 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
10d60 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
10d70 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
10d80 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
10d90 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
10da0 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
10db0 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
10dc0 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
10dd0 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
10de0 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
10df0 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
10e00 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
10e10 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
10e20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
10e30 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
10e40 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
10e50 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
10e60 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
10e70 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
10e80 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
10e90 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
10ea0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
10eb0 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
10ec0 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
10ed0 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
10ee0 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
10ef0 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
10f00 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
10f10 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10f20 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
10f30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
10f40 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
10f50 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10f60 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
10f70 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
10f80 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
10f90 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
10fa0 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
10fb0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
10fc0 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
10fd0 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
10fe0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
10ff0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
11000 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
11010 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
11020 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
11030 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
11040 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
11050 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  nnections.** MET
11060 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
11070 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
11080 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
11090 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
110a0 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
110b0 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
110c0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
110d0 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
110e0 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
110f0 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
11100 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
11110 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
11120 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
11130 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
11140 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11150 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
11160 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11170 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
11180 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
11190 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
111a0 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
111b0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
111c0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
111d0 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
111e0 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
111f0 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
11200 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
11210 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
11220 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11230 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
11240 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
11250 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
11260 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
11270 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
11280 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
11290 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
112a0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
112b0 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
112c0 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
112d0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
112e0 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
112f0 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
11300 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
11310 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
11320 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
11330 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
11340 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
11350 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
11360 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
11370 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
11380 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
11390 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
113a0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
113b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
113c0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
113d0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
113e0 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
113f0 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
11400 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
11410 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
11420 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
11430 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
11440 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
11450 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
11460 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
11470 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
11480 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
11490 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
114a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
114b0 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
114c0 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
114d0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
114e0 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
114f0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
11500 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
11510 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
11520 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
11530 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
11540 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
11550 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
11560 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
11570 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
11580 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
11590 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
115a0 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
115b0 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
115c0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
115d0 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
115e0 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
115f0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
11600 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
11610 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
11620 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
11630 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
11640 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
11650 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
11660 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
11670 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
11680 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
11690 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
116a0 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
116b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
116c0 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
116d0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
116e0 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
116f0 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
11700 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
11710 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
11720 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
11730 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
11740 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
11750 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
11760 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
11770 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
11780 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
11790 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
117a0 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
117b0 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
117c0 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
117d0 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
117e0 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
117f0 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
11800 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
11810 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
11820 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
11830 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
11840 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
11850 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
11860 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
11870 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
11880 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
11890 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
118a0 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
118b0 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
118c0 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
118d0 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
118e0 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
118f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
11900 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
11910 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
11920 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
11930 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
11940 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
11950 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
11960 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
11970 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
11980 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
11990 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
119a0 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
119b0 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
119c0 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
119d0 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
119e0 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
119f0 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
11a00 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
11a10 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
11a20 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
11a30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11a40 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
11a50 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
11a60 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
11a70 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
11a80 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
11a90 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
11aa0 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
11ab0 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
11ac0 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
11ad0 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
11ae0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11af0 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
11b00 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
11b10 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
11b20 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
11b30 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
11b40 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
11b50 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
11b60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11b70 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
11b80 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
11b90 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
11ba0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11bb0 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  .  For example,.
11bc0 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
11bd0 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
11be0 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
11bf0 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
11c00 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
11c10 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
11c20 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
11c30 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
11c40 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
11c50 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
11c60 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
11c70 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
11c80 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
11c90 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
11ca0 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
11cb0 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
11cc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
11cd0 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
11ce0 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
11cf0 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
11d00 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
11d10 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
11d20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
11d30 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
11d40 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
11d50 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
11d60 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
11d70 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
11d80 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
11d90 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
11da0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11db0 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
11dc0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
11dd0 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
11de0 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
11df0 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
11e00 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
11e10 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
11e20 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
11e30 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
11e40 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
11e50 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
11e60 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
11e70 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
11e80 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
11e90 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
11ea0 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
11eb0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
11ec0 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
11ed0 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
11ee0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
11ef0 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
11f00 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
11f10 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
11f20 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
11f30 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
11f40 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
11f50 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
11f60 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
11f70 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
11f80 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
11f90 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
11fa0 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
11fb0 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
11fc0 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
11fd0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
11fe0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11ff0 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
12000 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
12010 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12020 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
12030 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
12040 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
12050 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
12060 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
12070 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
12080 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
12090 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
120a0 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
120b0 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
120c0 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
120d0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
120e0 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
120f0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
12100 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
12110 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
12120 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
12130 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
12140 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
12150 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
12160 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
12170 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
12180 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
12190 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
121a0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
121b0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
121c0 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
121d0 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
121e0 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
121f0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
12200 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
12210 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
12220 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
12230 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
12240 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
12250 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
12260 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
12270 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
12280 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
12290 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
122a0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
122b0 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
122c0 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
122d0 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
122e0 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
122f0 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
12300 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
12310 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
12320 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
12330 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
12340 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
12350 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
12360 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
12370 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
12380 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
12390 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
123a0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
123b0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
123c0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
123d0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
123e0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
123f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12400 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
12410 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
12420 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
12430 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12440 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
12450 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
12460 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
12470 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
12480 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
12490 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
124a0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
124b0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
124c0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
124d0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
124e0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
124f0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
12500 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
12510 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
12520 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
12530 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
12540 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
12550 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
12560 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
12570 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
12580 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
12590 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
125a0 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
125b0 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
125c0 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
125d0 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
125e0 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
125f0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12600 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
12610 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
12620 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
12630 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
12640 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
12650 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
12660 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
12670 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
12680 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
12690 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
126a0 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
126b0 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
126c0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
126d0 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
126e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
126f0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
12700 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
12710 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
12720 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12730 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
12740 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12750 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
12760 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12770 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
12780 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
12790 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
127a0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
127b0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
127c0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
127d0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
127e0 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
127f0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
12800 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
12810 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
12820 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
12830 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12840 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
12850 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
12860 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
12870 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
12880 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
12890 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
128a0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
128b0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
128c0 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
128d0 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
128e0 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
128f0 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
12900 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
12910 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
12920 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
12930 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
12940 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
12950 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
12960 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12970 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
12980 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
12990 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
129a0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
129b0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
129c0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
129d0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
129e0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
129f0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
12a00 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
12a10 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
12a20 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
12a30 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
12a40 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
12a50 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
12a60 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
12a70 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
12a80 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
12a90 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12aa0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
12ab0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12ac0 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
12ad0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12ae0 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
12af0 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
12b00 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
12b10 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
12b20 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
12b30 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
12b40 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
12b50 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
12b60 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
12b70 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
12b80 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
12b90 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
12ba0 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
12bb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12bc0 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
12bd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
12be0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
12bf0 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
12c00 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
12c10 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
12c20 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
12c30 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12c40 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
12c50 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
12c60 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
12c70 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
12c80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12c90 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
12ca0 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
12cb0 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
12cc0 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
12cd0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
12ce0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12cf0 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
12d00 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
12d10 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
12d20 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
12d30 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
12d40 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
12d50 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
12d60 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
12d70 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
12d80 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
12d90 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
12da0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
12db0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
12dc0 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
12dd0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
12de0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
12df0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12e00 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
12e10 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
12e20 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
12e30 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
12e40 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
12e50 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
12e60 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12e70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
12e80 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
12e90 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
12ea0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
12eb0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
12ec0 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
12ed0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
12ee0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
12ef0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
12f00 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
12f10 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12f20 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12f30 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
12f40 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
12f50 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
12f60 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
12f70 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12f80 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
12f90 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
12fa0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12fb0 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
12fc0 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
12fd0 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
12fe0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
12ff0 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
13000 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
13010 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
13020 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
13030 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
13040 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
13050 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
13060 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13070 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
13080 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13090 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
130a0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
130b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
130c0 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  TMALLOC option t
130d0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
130e0 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
130f0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
13100 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
13110 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
13120 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13130 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  re..** The [sqli
13140 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
13150 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
13160 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
13170 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
13180 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
13190 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
131a0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
131b0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
131c0 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
131d0 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
131e0 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
131f0 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
13200 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
13210 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
13220 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
13230 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
13240 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
13250 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
13260 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13270 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
13280 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
13290 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
132a0 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
132b0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
132c0 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  S option takes s
132d0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
132e0 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69  f type int,.** i
132f0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
13300 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
13310 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
13320 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
13330 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  n of.** memory a
13340 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
13350 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
13360 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
13370 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a  tatistics are.**
13380 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66   disabled, the f
13390 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
133a0 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
133b0 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
133c0 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
133d0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
133e0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
133f0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
13400 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
13410 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
13420 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
13430 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
13440 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
13450 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20  _status64()].** 
13460 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
13470 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13480 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
13490 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
134a0 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
134b0 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
134c0 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
134d0 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
134e0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
134f0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
13500 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
13510 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
13520 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
13530 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13540 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
13550 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13560 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
13570 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
13580 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
13590 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  CH option specif
135a0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
135b0 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  ory buffer.** th
135c0 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
135d0 65 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65  e for scratch me
135e0 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61  mory.  ^(There a
135f0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
13600 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f  ts.** to SQLITE_
13610 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20  CONFIG_SCRATCH: 
13620 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
13630 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
13640 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
13650 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
13660 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
13670 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
13680 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
13690 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
136a0 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
136b0 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
136c0 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
136d0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
136e0 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73  ).)^.** The firs
136f0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
13700 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
13710 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
13720 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
13730 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
13740 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
13750 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f   ^SQLite will no
13760 74 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20  t use more than 
13770 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66  one scratch buff
13780 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a  ers per thread..
13790 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
137a0 6e 65 76 65 72 20 72 65 71 75 65 73 74 20 61 20  never request a 
137b0 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
137c0 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
137d0 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
137e0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
137f0 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  ze..** ^If SQLit
13800 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
13810 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
13820 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
13830 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
13840 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
13850 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
13860 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
13870 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
13880 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
13890 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
138a0 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68  eeded.<p>.** ^Wh
138b0 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  en the applicati
138c0 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20  on provides any 
138d0 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63  amount of scratc
138e0 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a  h memory using.*
138f0 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
13900 53 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20  SCRATCH, SQLite 
13910 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61  avoids unnecessa
13920 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c  ry large.** [sql
13930 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70  ite3_malloc|heap
13940 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a   allocations]..*
13950 2a 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20  * This can help 
13960 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72  [Robson proof|pr
13970 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  event memory all
13980 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73  ocation failures
13990 5d 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a  ] due to heap.**
139a0 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69   fragmentation i
139b0 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62  n low-memory emb
139c0 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a  edded systems..*
139d0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
139e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
139f0 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
13a00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
13a10 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
13a20 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
13a30 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
13a40 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
13a50 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a   a memory pool.*
13a60 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  * that SQLite ca
13a70 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 61  n use for the da
13a80 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
13a90 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
13aa0 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  lt page.** cache
13ab0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
13ac0 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
13ad0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
13ae0 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e  is a no-op if an
13af0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
13b00 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
13b10 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13b20 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
13b30 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
13b40 46 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a  FIG_PCACHE2]..**
13b50 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
13b60 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
13b70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
13b80 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65  ECACHE: A pointe
13b90 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61  r to.** 8-byte a
13ba0 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70  ligned memory (p
13bb0 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f  Mem), the size o
13bc0 66 20 65 61 63 68 20 70 61 67 65 20 63 61 63 68  f each page cach
13bd0 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20  e line (sz),.** 
13be0 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
13bf0 66 20 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e  f cache lines (N
13c00 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67  )..** The sz arg
13c10 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
13c20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
13c30 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
13c40 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65   page.** (a powe
13c50 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
13c60 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29 20   512 and 65536) 
13c70 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20  plus some extra 
13c80 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a  bytes for each.*
13c90 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20  * page header.  
13ca0 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65  ^The number of e
13cb0 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64 65  xtra bytes neede
13cc0 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68 65  d by the page he
13cd0 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64  ader.** can be d
13ce0 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20  etermined using 
13cf0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
13d00 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a  CACHE_HDRSZ]..**
13d10 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73   ^It is harmless
13d20 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
13d30 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
13d40 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61  ** for the sz pa
13d50 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61  rameter to be la
13d60 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73  rger than necess
13d70 61 72 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a  ary.  The pMem.*
13d80 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
13d90 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
13da0 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f   pointer or a po
13db0 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
13dc0 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c  te.** aligned bl
13dd0 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66  ock of memory of
13de0 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
13df0 79 74 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a  ytes, otherwise.
13e00 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  ** subsequent be
13e10 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
13e20 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d  ned..** ^When pM
13e30 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  em is not NULL, 
13e40 53 51 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69  SQLite will stri
13e50 76 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65  ve to use the me
13e60 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a  mory provided.**
13e70 20 74 6f 20 73 61 74 69 73 66 79 20 70 61 67 65   to satisfy page
13e80 20 63 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61   cache needs, fa
13e90 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73  lling back to [s
13ea0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
13eb0 20 69 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61   if.** a page ca
13ec0 63 68 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67  che line is larg
13ed0 65 72 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73  er than sz bytes
13ee0 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68   or if all of th
13ef0 65 20 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a  e pMem buffer.**
13f00 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a   is exhausted..*
13f10 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55  * ^If pMem is NU
13f20 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d  LL and N is non-
13f30 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20  zero, then each 
13f40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13f50 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69  ion.** does an i
13f60 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f  nitial bulk allo
13f70 63 61 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20  cation for page 
13f80 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  cache memory.** 
13f90 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
13fa0 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65  lloc()] sufficie
13fb0 6e 74 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c  nt for N cache l
13fc0 69 6e 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73  ines if N is pos
13fd0 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d  itive or.** of -
13fe0 31 30 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20  1024*N bytes if 
13ff0 4e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e  N is negative, .
14000 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a   ^If additional.
14010 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
14020 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
14030 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
14040 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 69 6e  ovided by the in
14050 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74  itial.** allocat
14060 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ion, then SQLite
14070 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
14080 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61  3_malloc()] sepa
14090 72 61 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a  rately for each.
140a0 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61  ** additional ca
140b0 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a  che line. </dd>.
140c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
140d0 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74  ONFIG_HEAP]] <dt
140e0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
140f0 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
14100 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14110 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
14120 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
14130 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
14140 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65   .** that SQLite
14150 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c   will use for al
14160 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
14170 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14180 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f  on needs.** beyo
14190 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65  nd those provide
141a0 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  d for by [SQLITE
141b0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
141c0 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   and.** [SQLITE_
141d0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
141e0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54  ]..** ^The SQLIT
141f0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70  E_CONFIG_HEAP op
14200 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
14210 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
14220 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20   is compiled.** 
14230 77 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c  with either [SQL
14240 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
14250 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45  S3] or [SQLITE_E
14260 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
14270 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  nd returns.** [S
14280 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
14290 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73  invoked otherwis
142a0 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65  e..** ^There are
142b0 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
142c0 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
142d0 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d  G_HEAP:.** An 8-
142e0 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69  byte aligned poi
142f0 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
14300 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  ry,.** the numbe
14310 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
14320 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c  e memory buffer,
14330 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d   and the minimum
14340 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
14350 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72  ..** ^If the fir
14360 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
14370 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
14380 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51  is NULL, then SQ
14390 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20  Lite reverts.** 
143a0 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66  to using its def
143b0 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
143c0 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65  cator (the syste
143d0 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  m malloc() imple
143e0 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75  mentation),.** u
143f0 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72  ndoing any prior
14400 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
14410 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
14420 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a  LLOC].  ^If the.
14430 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
14440 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  r is not NULL th
14450 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
14460 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
14470 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
14480 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
14490 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
144a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
144b0 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
144c0 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
144d0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
144e0 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
144f0 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
14500 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
14510 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
14520 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
14530 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
14540 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
14550 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70  tion size is cap
14560 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65  ped at 2**12. Re
14570 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a  asonable values.
14580 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d  ** for the minim
14590 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
145a0 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f  ze are 2**5 thro
145b0 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a  ugh 2**8.</dd>.*
145c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
145d0 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74  NFIG_MUTEX]] <dt
145e0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
145f0 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
14600 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
14610 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69  ONFIG_MUTEX opti
14620 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14630 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
14640 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
14650 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
14660 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
14670 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
14680 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
14690 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
146a0 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20  ies alternative 
146b0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
146c0 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
146d0 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20  sed.** in place 
146e0 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
146f0 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
14700 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65  Lite.)^  ^SQLite
14710 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
14720 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
14730 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
14740 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
14750 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20  tructure before 
14760 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  the call to.** [
14770 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
14780 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53  ] returns. ^If S
14790 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
147a0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
147b0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
147c0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
147d0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
147e0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
147f0 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
14800 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
14810 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
14820 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
14830 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
14840 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
14850 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
14860 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
14870 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
14880 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
14890 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
148a0 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
148b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
148c0 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  _GETMUTEX]] <dt>
148d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
148e0 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  TMUTEX</dt>.** <
148f0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
14900 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
14910 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14920 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14930 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
14940 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
14950 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
14960 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
14970 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
14980 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
14990 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
149a0 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
149b0 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
149c0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
149d0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
149e0 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
149f0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
14a00 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
14a10 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
14a20 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
14a30 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
14a40 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
14a50 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
14a60 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
14a70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
14a80 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
14a90 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
14aa0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
14ab0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
14ac0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
14ad0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
14ae0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
14af0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
14b00 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
14b10 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
14b20 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
14b30 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
14b40 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
14b50 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
14b60 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
14b70 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f  NFIG_GETMUTEX co
14b80 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14b90 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
14ba0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
14bb0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14bc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14bd0 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c  KASIDE]] <dt>SQL
14be0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
14bf0 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
14c00 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
14c10 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
14c20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
14c30 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
14c40 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65  determine.** the
14c50 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66   default size of
14c60 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
14c70 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62  y on each [datab
14c80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
14c90 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
14ca0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
14cb0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
14cc0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
14cd0 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
14ce0 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
14cf0 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
14d00 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
14d10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14d20 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f  on.)^  ^(SQLITE_
14d30 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14d40 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e  .** sets the <i>
14d50 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b  default</i> look
14d60 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20  aside size. The 
14d70 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
14d80 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f  _LOOKASIDE].** o
14d90 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65  ption to [sqlite
14da0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
14db0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
14dc0 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
14dd0 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
14de0 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
14df0 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
14e00 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14e10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14e20 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
14e30 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
14e40 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
14e50 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14e60 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  G_PCACHE2 option
14e70 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
14e80 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
14e90 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
14ea0 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  to an [sqlite3_p
14eb0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
14ec0 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
14ed0 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ject specifies.*
14ee0 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  * the interface 
14ef0 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
14f00 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
14f10 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c  ation.)^.** ^SQL
14f20 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
14f30 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14f40 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
14f50 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a  ] object.</dd>.*
14f60 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14f70 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d  NFIG_GETPCACHE2]
14f80 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14f90 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f  FIG_GETPCACHE2</
14fa0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
14fb0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14fc0 47 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f  GETPCACHE2 optio
14fd0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14fe0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
14ff0 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
15000 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  to an [sqlite3_p
15010 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
15020 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20  object.  SQLite 
15030 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65  copies of.** the
15040 20 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 61   current page ca
15050 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
15060 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a  on into that obj
15070 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ect.)^ </dd>.**.
15080 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15090 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c  IG_LOG]] <dt>SQL
150a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f  ITE_CONFIG_LOG</
150b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20  dt>.** <dd> The 
150c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
150d0 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  G option is used
150e0 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68   to configure th
150f0 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62  e SQLite.** glob
15100 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a  al [error log]..
15110 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f  ** (^The SQLITE_
15120 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
15130 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
15140 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72  ments: a pointer
15150 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   to a.** functio
15160 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69  n with a call si
15170 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28  gnature of void(
15180 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  *)(void*,int,con
15190 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61  st char*), .** a
151a0 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  nd a pointer to 
151b0 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75  void. ^If the fu
151c0 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
151d0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69  s not NULL, it i
151e0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20  s.** invoked by 
151f0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
15200 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20  to process each 
15210 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20  logging event.  
15220 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  ^If the.** funct
15230 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e  ion pointer is N
15240 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ULL, the [sqlite
15250 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61  3_log()] interfa
15260 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d  ce becomes a no-
15270 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64  op..** ^The void
15280 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
15290 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
152a0 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43  ment to SQLITE_C
152b0 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20  ONFIG_LOG is.** 
152c0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
152d0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
152e0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70  meter to the app
152f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
15300 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
15310 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61  ion whenever tha
15320 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  t function is in
15330 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63  voked.  ^The sec
15340 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
15350 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66  .** the logger f
15360 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70  unction is a cop
15370 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70  y of the first p
15380 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
15390 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
153a0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
153b0 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74   call and is int
153c0 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72  ended to be a [r
153d0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61  esult code] or a
153e0 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  n.** [extended r
153f0 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54  esult code].  ^T
15400 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
15410 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
15420 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f   logger is.** lo
15430 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20  g message after 
15440 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b  formatting via [
15450 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
15460 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ()]..** The SQLi
15470 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72  te logging inter
15480 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e  face is not reen
15490 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65  trant; the logge
154a0 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75  r function.** su
154b0 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70  pplied by the ap
154c0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
154d0 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51  ot invoke any SQ
154e0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
154f0 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68  ** In a multi-th
15500 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
15510 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  on, the applicat
15520 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
15530 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  er.** function m
15540 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
15550 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
15560 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
15570 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  RI]] <dt>SQLITE_
15580 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64  CONFIG_URI.** <d
15590 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  d>^(The SQLITE_C
155a0 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e  ONFIG_URI option
155b0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
155c0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
155d0 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d   int..** If non-
155e0 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68  zero, then URI h
155f0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
15600 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20  lly enabled. If 
15610 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
15620 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55   zero,.** then U
15630 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
15640 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
15650 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64  .)^ ^If URI hand
15660 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
15670 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c  .** enabled, all
15680 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65   filenames passe
15690 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d to [sqlite3_op
156a0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
156b0 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  open_v2()],.** [
156c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
156d0 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65  ] or.** specifie
156e0 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54  d as part of [AT
156f0 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61  TACH] commands a
15700 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
15710 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65  s URIs, regardle
15720 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72  ss.** of whether
15730 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c   or not the [SQL
15740 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
15750 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
15760 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
15770 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
15780 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67  ned. ^If it is g
15790 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
157a0 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a  , filenames are.
157b0 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65  ** only interpre
157c0 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74  ted as URIs if t
157d0 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  he SQLITE_OPEN_U
157e0 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  RI flag is set w
157f0 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  hen the.** datab
15800 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
15810 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64  s opened. ^(By d
15820 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64  efault, URI hand
15830 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
15840 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68  .** disabled. Th
15850 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
15860 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62  may be changed b
15870 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68  y compiling with
15880 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
15890 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20  USE_URI] symbol 
158a0 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  defined.)^.**.**
158b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
158c0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
158d0 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SCAN]] <dt>SQLIT
158e0 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
158f0 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20  G_INDEX_SCAN.** 
15900 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
15910 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
15920 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f  INDEX_SCAN optio
15930 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15940 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75   integer.** argu
15950 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e  ment which is in
15960 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62  terpreted as a b
15970 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20  oolean in order 
15980 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
15990 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20  able.** the use 
159a0 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
159b0 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
159c0 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20  le scans in the 
159d0 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e  query optimizer.
159e0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
159f0 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65   setting is dete
15a00 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65  rmined.** by the
15a10 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43   [SQLITE_ALLOW_C
15a20 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
15a30 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  AN] compile-time
15a40 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22   option, or is "
15a50 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63  on".** if that c
15a60 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15a70 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a  on is omitted..*
15a80 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f  * The ability to
15a90 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65   disable the use
15aa0 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
15ab0 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
15ac0 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20  ble scans.** is 
15ad0 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63  because some inc
15ae0 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c  orrectly coded l
15af0 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f  egacy applicatio
15b00 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63  ns might malfunc
15b10 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65  tion.** when the
15b20 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73   optimization is
15b30 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69   enabled.  Provi
15b40 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79  ding the ability
15b50 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74   to.** disable t
15b60 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
15b70 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72  allows the older
15b80 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74  , buggy applicat
15b90 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b  ion code to work
15ba0 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e  .** without chan
15bb0 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77  ge even with new
15bc0 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
15bd0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  QLite..**.** [[S
15be0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15bf0 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43  CHE]] [[SQLITE_C
15c00 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d  ONFIG_GETPCACHE]
15c10 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
15c20 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e  CONFIG_PCACHE an
15c30 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  d SQLITE_CONFIG_
15c40 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64  GETPCACHE.** <dd
15c50 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20  > These options 
15c60 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64  are obsolete and
15c70 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
15c80 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e  sed by new code.
15c90 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74  .** They are ret
15ca0 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
15cb0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
15cc0 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f  y but are now no
15cd0 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  -ops..** </dd>.*
15ce0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15cf0 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a  NFIG_SQLLOG]].**
15d00 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15d10 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64  IG_SQLLOG.** <dd
15d20 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  >This option is 
15d30 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
15d40 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70  f sqlite is comp
15d50 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
15d60 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
15d70 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63  SQLLOG] pre-proc
15d80 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69  essor macro defi
15d90 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61  ned. The first a
15da0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a  rgument should.*
15db0 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  * be a pointer t
15dc0 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
15dd0 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69  type void(*)(voi
15de0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73  d*,sqlite3*,cons
15df0 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a  t char*, int)..*
15e00 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f  * The second sho
15e10 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28  uld be of type (
15e20 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c  void*). The call
15e30 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
15e40 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a  by the library.*
15e50 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72  * in three separ
15e60 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ate circumstance
15e70 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  s, identified by
15e80 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
15e90 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72  d as the.** four
15ea0 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66  th parameter. If
15eb0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
15ec0 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e  meter is 0, then
15ed0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
15ee0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73  nnection.** pass
15ef0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
15f00 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75   argument has ju
15f10 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  st been opened. 
15f20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
15f30 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  nt.** points to 
15f40 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e  a buffer contain
15f50 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ing the name of 
15f60 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
15f70 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a  e file. If the.*
15f80 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
15f90 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68  er is 1, then th
15fa0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
15fb0 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70  that the third p
15fc0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e  arameter.** poin
15fd0 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62  ts to has just b
15fe0 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72  een executed. Or
15ff0 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20  , if the fourth 
16000 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20  parameter is 2, 
16010 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e  then.** the conn
16020 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73  ection being pas
16030 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
16040 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62  d parameter is b
16050 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65  eing closed. The
16060 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
16070 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55  ter is passed NU
16080 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e  LL In this case.
16090 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20    An example of 
160a0 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f  using this.** co
160b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
160c0 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69  on can be seen i
160d0 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c  n the "test_sqll
160e0 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c  og.c" source fil
160f0 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f  e in.** the cano
16100 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75  nical SQLite sou
16110 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a  rce tree.</dd>.*
16120 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16130 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  NFIG_MMAP_SIZE]]
16140 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16150 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a  ONFIG_MMAP_SIZE.
16160 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43  ** <dd>^SQLITE_C
16170 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
16180 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74  takes two 64-bit
16190 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65   integer (sqlite
161a0 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a  3_int64) values.
161b0 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20  ** that are the 
161c0 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a  default mmap siz
161d0 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66  e limit (the def
161e0 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72  ault setting for
161f0 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  .** [PRAGMA mmap
16200 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20  _size]) and the 
16210 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
16220 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e  mmap size limit.
16230 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
16240 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20   setting can be 
16250 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61  overridden by ea
16260 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
16270 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  ection using.** 
16280 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47  either the [PRAG
16290 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f  MA mmap_size] co
162a0 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69  mmand, or by usi
162b0 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ng the.** [SQLIT
162c0 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
162d0 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e  E] file control.
162e0 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20    ^(The maximum 
162f0 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
16300 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c  e.** will be sil
16310 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
16320 69 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20  if necessary so 
16330 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74  that it does not
16340 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63   exceed the.** c
16350 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69  ompile-time maxi
16360 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65  mum mmap size se
16370 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  t by the.** [SQL
16380 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a  ITE_MAX_MMAP_SIZ
16390 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  E] compile-time 
163a0 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66  option.)^.** ^If
163b0 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74   either argument
163c0 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20   to this option 
163d0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
163e0 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20  n that argument 
163f0 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f  is.** changed to
16400 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   its compile-tim
16410 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  e default..**.**
16420 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16430 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d  _WIN32_HEAPSIZE]
16440 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
16450 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
16460 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68  PSIZE.** <dd>^Th
16470 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16480 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f  WIN32_HEAPSIZE o
16490 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
164a0 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74  ailable if SQLit
164b0 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  e is.** compiled
164c0 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74   for Windows wit
164d0 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49  h the [SQLITE_WI
164e0 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d  N32_MALLOC] pre-
164f0 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a  processor macro.
16500 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c  ** defined. ^SQL
16510 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
16520 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20  _HEAPSIZE takes 
16530 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65  a 32-bit unsigne
16540 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a  d integer value.
16550 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65  ** that specifie
16560 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  s the maximum si
16570 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65  ze of the create
16580 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  d heap..**.** [[
16590 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
165a0 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20  ACHE_HDRSZ]].** 
165b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
165c0 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a  G_PCACHE_HDRSZ.*
165d0 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
165e0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
165f0 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b  HDRSZ option tak
16600 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
16610 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
16620 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
16630 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72  n integer and wr
16640 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69  ites into that i
16650 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65  nteger the numbe
16660 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79  r of extra.** by
16670 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71  tes per page req
16680 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70  uired for each p
16690 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43  age in [SQLITE_C
166a0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
166b0 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20  ..** The amount 
166c0 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72  of extra space r
166d0 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e  equired can chan
166e0 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ge depending on 
166f0 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a  the compiler,.**
16700 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d   target platform
16710 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  , and SQLite ver
16720 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  sion..**.** [[SQ
16730 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
16740 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  Z]].** <dt>SQLIT
16750 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a  E_CONFIG_PMASZ.*
16760 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
16770 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f  E_CONFIG_PMASZ o
16780 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
16790 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77  ngle parameter w
167a0 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e  hich.** is an un
167b0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
167c0 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e  nd sets the "Min
167d0 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66  imum PMA Size" f
167e0 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65  or the multithre
167f0 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74  aded.** sorter t
16800 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20  o that integer. 
16810 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e   The default min
16820 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73  imum PMA Size is
16830 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b   set by the.** [
16840 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d  SQLITE_SORTER_PM
16850 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ASZ] compile-tim
16860 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74  e option.  New t
16870 68 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63  hreads are launc
16880 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77  hed.** to help w
16890 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69  ith sort operati
168a0 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68  ons when multith
168b0 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a  readed sorting.*
168c0 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73  * is enabled (us
168d0 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20  ing the [PRAGMA 
168e0 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64  threads] command
168f0 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74  ) and the amount
16900 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74   of content.** t
16910 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 65  o be sorted exce
16920 65 64 73 20 74 68 65 20 70 61 67 65 20 73 69 7a  eds the page siz
16930 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69  e times the mini
16940 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50  mum of the.** [P
16950 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65  RAGMA cache_size
16960 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68  ] setting and th
16970 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  is value..**.** 
16980 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16990 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d  STMTJRNL_SPILL]]
169a0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
169b0 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
169c0 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  PILL.** <dd>^The
169d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
169e0 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70  TMTJRNL_SPILL op
169f0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
16a00 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
16a10 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74  ich.** becomes t
16a20 68 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f  he [statement jo
16a30 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d  urnal] spill-to-
16a40 64 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20  disk threshold. 
16a50 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20   .** [Statement 
16a60 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65  journals] are he
16a70 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74  ld in memory unt
16a80 69 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28 69  il their size (i
16a90 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65  n bytes).** exce
16aa0 65 64 73 20 74 68 69 73 20 74 68 72 65 73 68 6f  eds this thresho
16ab0 6c 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69  ld, at which poi
16ac0 6e 74 20 74 68 65 79 20 61 72 65 20 77 72 69 74  nt they are writ
16ad0 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20  ten to disk..** 
16ae0 4f 72 20 69 66 20 74 68 65 20 74 68 72 65 73 68  Or if the thresh
16af0 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65  old is -1, state
16b00 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72  ment journals ar
16b10 65 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a  e always held.**
16b20 20 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20   exclusively in 
16b30 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65  memory..** Since
16b40 20 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20   many statement 
16b50 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62  journals never b
16b60 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74  ecome large, set
16b70 74 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a  ting the spill.*
16b80 2a 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61  * threshold to a
16b90 20 76 61 6c 75 65 20 73 75 63 68 20 61 73 20 36   value such as 6
16ba0 34 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79  4KiB can greatly
16bb0 20 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75   reduce the amou
16bc0 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71  nt of.** I/O req
16bd0 75 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74  uired to support
16be0 20 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62   statement rollb
16bf0 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61  ack..** The defa
16c00 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ult value for th
16c10 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f  is setting is co
16c20 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a  ntrolled by the.
16c30 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a  ** [SQLITE_STMTJ
16c40 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69  RNL_SPILL] compi
16c50 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
16c60 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
16c70 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16c80 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
16c90 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
16ca0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16cb0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
16cc0 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
16cd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16ce0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
16cf0 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
16d00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16d10 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
16d20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
16d30 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
16d40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16d50 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
16d60 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
16d70 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
16d80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16d90 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
16da0 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
16db0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
16dc0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
16dd0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
16de0 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
16df0 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
16e00 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
16e10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
16e20 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
16e30 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
16e40 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
16e50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16e60 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
16e70 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
16e80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16e90 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
16ea0 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
16eb0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
16ec0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
16ed0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16ee0 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
16ef0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
16f00 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
16f10 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
16f20 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
16f30 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
16f40 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
16f50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16f60 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
16f70 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
16f80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16f90 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
16fa0 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d        14  /* no-
16fb0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
16fc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
16fd0 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
16fe0 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
16ff0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
17000 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
17010 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
17020 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17030 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20  E_CONFIG_URI    
17040 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74        17  /* int
17050 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17060 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
17070 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71  2      18  /* sq
17080 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
17090 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
170a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
170b0 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20  GETPCACHE2   19 
170c0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
170d0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
170e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
170f0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
17100 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a  NDEX_SCAN 20  /*
17110 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
17120 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
17130 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f  LLOG       21  /
17140 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a  * xSqllog, void*
17150 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17160 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
17170 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71  IZE    22  /* sq
17180 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c  lite3_int64, sql
17190 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64  ite3_int64 */.#d
171a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
171b0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
171c0 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69  ZE      23  /* i
171d0 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66  nt nByte */.#def
171e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
171f0 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20  G_PCACHE_HDRSZ  
17200 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74        24  /* int
17210 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65   *psz */.#define
17220 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
17230 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20  MASZ            
17240 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e     25  /* unsign
17250 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a  ed int szPma */.
17260 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17270 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
17280 50 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f 2a  PILL      26  /*
17290 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f   int nByte */../
172a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
172b0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
172c0 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
172d0 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
172e0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
172f0 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
17300 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
17310 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
17320 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
17330 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
17340 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
17350 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
17360 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
17370 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
17380 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
17390 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
173a0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
173b0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
173c0 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
173d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
173e0 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
173f0 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
17400 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
17410 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
17420 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
17430 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
17440 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
17450 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
17460 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
17470 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
17480 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
17490 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
174a0 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
174b0 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
174c0 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
174d0 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
174e0 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
174f0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
17500 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
17510 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
17520 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
17530 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
17540 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
17550 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
17560 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
17570 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
17580 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
17590 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
175a0 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
175b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
175c0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
175d0 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
175e0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
175f0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
17600 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
17610 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
17620 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
17630 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
17640 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
17650 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
17660 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
17670 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17680 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
17690 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
176a0 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
176b0 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
176c0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
176d0 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
176e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
176f0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
17700 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
17710 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
17720 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
17730 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
17740 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
17750 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
17760 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
17770 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
17780 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17790 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
177a0 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
177b0 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
177c0 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
177d0 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
177e0 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
177f0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
17800 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
17810 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
17820 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
17830 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
17840 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
17850 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
17860 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
17870 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
17880 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
17890 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
178a0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
178b0 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65   ^(The lookaside
178c0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69   memory.** confi
178d0 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64  guration for a d
178e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
178f0 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63  on can only be c
17900 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74  hanged when that
17910 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
17920 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
17930 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20  using lookaside 
17940 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74  memory, or in ot
17950 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65  her words.** whe
17960 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76  n the "current v
17970 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62  alue" returned b
17980 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62  y.** [sqlite3_db
17990 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49  _status](D,[SQLI
179a0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
179b0 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72  IDE],...) is zer
179c0 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  o..** Any attemp
179d0 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  t to change the 
179e0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
179f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77   configuration w
17a00 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  hen lookaside.**
17a10 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73   memory is in us
17a20 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e  e leaves the con
17a30 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61  figuration uncha
17a40 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73  nged and returns
17a50 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53   .** [SQLITE_BUS
17a60 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Y].)^</dd>.**.**
17a70 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
17a80 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
17a90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
17aa0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
17ab0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
17ac0 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f  disable the enfo
17ad0 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66  rcement of.** [f
17ae0 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
17af0 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20  raints].  There 
17b00 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
17b10 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
17b20 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
17b30 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
17b40 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
17b50 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b   0 to disable FK
17b60 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a   enforcement,.**
17b70 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
17b80 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
17b90 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  nt or negative t
17ba0 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72  o leave FK enfor
17bb0 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e  cement.** unchan
17bc0 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ged.  The second
17bd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
17be0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
17bf0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
17c00 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
17c10 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
17c20 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66  e whether FK enf
17c30 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20  orcement is off 
17c40 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  or on.** followi
17c50 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
17c60 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
17c70 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
17c80 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
17c90 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
17ca0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73  FK enforcement s
17cb0 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
17cc0 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
17cd0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
17ce0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
17cf0 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e  BLE_TRIGGER</dt>
17d00 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
17d10 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
17d20 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
17d30 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  le [CREATE TRIGG
17d40 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a  ER | triggers]..
17d50 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
17d60 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
17d70 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
17d80 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
17d90 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
17da0 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
17db0 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c  isable triggers,
17dc0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
17dd0 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20  enable triggers 
17de0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
17df0 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
17e00 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
17e10 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
17e20 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
17e30 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
17e40 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
17e50 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
17e60 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
17e70 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20  er triggers are 
17e80 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
17e90 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
17ea0 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
17eb0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17ec0 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
17ed0 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
17ee0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72  hich case the tr
17ef0 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73  igger setting is
17f00 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
17f10 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
17f20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
17f30 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f  FIG_ENABLE_FTS3_
17f40 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a  TOKENIZER</dt>.*
17f50 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
17f60 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
17f70 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
17f80 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e   the two-argumen
17f90 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  t.** version of 
17fa0 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69  the [fts3_tokeni
17fb0 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  zer()] function 
17fc0 77 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66  which is part of
17fd0 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66   the.** [FTS3] f
17fe0 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20  ull-text search 
17ff0 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e  engine extension
18000 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
18010 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
18020 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
18030 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
18040 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
18050 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
18060 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f   disable fts3_to
18070 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20  kenizer() or.** 
18080 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
18090 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65  le fts3_tokenize
180a0 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20  r() or negative 
180b0 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
180c0 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ting.** unchange
180d0 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
180e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
180f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
18100 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
18110 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
18120 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
18130 65 20 77 68 65 74 68 65 72 20 66 74 73 33 5f 74  e whether fts3_t
18140 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61  okenizer is disa
18150 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
18160 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
18170 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
18180 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
18190 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
181a0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
181b0 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65   case the new se
181c0 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
181d0 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
181e0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
181f0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18200 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f  LE_LOAD_EXTENSIO
18210 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  N</dt>.** <dd> ^
18220 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
18230 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
18240 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71   disable the [sq
18250 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
18260 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  sion()].** inter
18270 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74  face independent
18280 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f  ly of the [load_
18290 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c  extension()] SQL
182a0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
182b0 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  e [sqlite3_enabl
182c0 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
182d0 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20  ()] API enables 
182e0 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68  or disables both
182f0 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73   the.** C-API [s
18300 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
18310 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65  nsion()] and the
18320 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c   SQL function [l
18330 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
18340 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
18350 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
18360 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
18370 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72 73 74  * When the first
18380 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
18390 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 31  s interface is 1
183a0 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20  , then only the 
183b0 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62  C-API is.** enab
183c0 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  led and the SQL 
183d0 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73  function remains
183e0 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74   disabled.  If t
183f0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18400 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74  t to.** this int
18410 65 72 66 61 63 65 20 69 73 20 30 2c 20 74 68 65  erface is 0, the
18420 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49  n both the C-API
18430 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e   and the SQL fun
18440 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c  ction are disabl
18450 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  ed..** If the fi
18460 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
18470 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e  -1, then no chan
18480 67 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20  ges are made to 
18490 73 74 61 74 65 20 6f 66 20 65 69 74 68 65 72 20  state of either 
184a0 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20  the.** C-API or 
184b0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
184c0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
184d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
184e0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
184f0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
18500 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
18510 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
18520 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65   whether [sqlite
18530 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
18540 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
18550 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20   is disabled or 
18560 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e  enabled followin
18570 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
18580 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18590 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e  er may.** be a N
185a0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20  ULL pointer, in 
185b0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e  which case the n
185c0 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  ew setting is no
185d0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
185e0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
185f0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18600 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f  FIG_MAINDBNAME</
18610 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
18620 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
18630 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e   to change the n
18640 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e  ame of the "main
18650 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63  " database.** sc
18660 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65  hema.  ^The sole
18670 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
18680 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73  ointer to a cons
18690 74 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67  tant UTF8 string
186a0 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62  .** which will b
186b0 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63  ecome the new sc
186c0 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61  hema name in pla
186d0 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e  ce of "main".  ^
186e0 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e  SQLite.** does n
186f0 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f  ot make a copy o
18700 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73  f the new main s
18710 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e  chema name strin
18720 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63  g, so the applic
18730 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e  ation.** must en
18740 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61 72  sure that the ar
18750 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e  gument passed in
18760 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47  to this DBCONFIG
18770 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61   option is uncha
18780 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66  nged.** until af
18790 74 65 72 20 74 68 65 20 64 61 74 61 62 61 73 65  ter the database
187a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
187b0 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  es..** </dd>.**.
187c0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
187d0 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f  CONFIG_NO_CKPT_O
187e0 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20  N_CLOSE</dt>.** 
187f0 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68  <dd> Usually, wh
18800 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69 6e  en a database in
18810 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f   wal mode is clo
18820 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64 20  sed or detached 
18830 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62  from a .** datab
18840 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69  ase handle, SQLi
18850 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 69  te checks if thi
18860 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74  s will mean that
18870 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e   there are now n
18880 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  o .** connection
18890 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20  s at all to the 
188a0 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c  database. If so,
188b0 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63   it performs a c
188c0 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70  heckpoint .** op
188d0 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63  eration before c
188e0 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65  losing the conne
188f0 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69  ction. This opti
18900 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 74  on may be used t
18910 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68  o.** override th
18920 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68  is behaviour. Th
18930 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
18940 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73  r passed to this
18950 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73   operation.** is
18960 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e 6f   an integer - no
18970 6e 2d 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c  n-zero to disabl
18980 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e  e checkpoints-on
18990 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20  -close, or zero 
189a0 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29  (the.** default)
189b0 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2e   to enable them.
189c0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
189d0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
189e0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
189f0 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69  .** into which i
18a00 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
18a10 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
18a20 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73  ther checkpoints
18a30 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76  -on-close.** hav
18a40 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20  e been disabled 
18a50 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65 20  - 0 if they are 
18a60 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20  not disabled, 1 
18a70 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20  if they are..** 
18a80 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
18a90 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
18aa0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49  ITE_DBCONFIG_MAI
18ab0 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20  NDBNAME         
18ac0 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74     1000 /* const
18ad0 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e   char* */.#defin
18ae0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
18af0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
18b00 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20          1001 /* 
18b10 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
18b20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18b30 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
18b40 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 31  FKEY           1
18b50 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  002 /* int int* 
18b60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18b70 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
18b80 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
18b90 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74   1003 /* int int
18ba0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18bb0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18bc0 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a  BLE_FTS3_TOKENIZ
18bd0 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69  ER 1004 /* int i
18be0 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
18bf0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
18c00 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e  NABLE_LOAD_EXTEN
18c10 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74  SION 1005 /* int
18c20 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
18c30 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18c40 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53  _NO_CKPT_ON_CLOS
18c50 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69  E      1006 /* i
18c60 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a  nt int* */.../*.
18c70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
18c80 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
18c90 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
18ca0 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  odes.** METHOD: 
18cb0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
18cc0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
18cd0 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
18ce0 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
18cf0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
18d00 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
18d10 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
18d20 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
18d30 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72   ^The extended r
18d40 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
18d50 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
18d60 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
18d70 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
18d80 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ity..*/.int sqli
18d90 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
18da0 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
18db0 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
18dc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18dd0 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
18de0 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  id.** METHOD: sq
18df0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  lite3.**.** ^Eac
18e00 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20  h entry in most 
18e10 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65  SQLite tables (e
18e20 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f  xcept for [WITHO
18e30 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
18e40 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75  ).** has a uniqu
18e50 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
18e60 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
18e70 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
18e80 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
18e90 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
18ea0 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
18eb0 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
18ec0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
18ed0 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
18ee0 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
18ef0 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
18f00 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
18f10 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
18f20 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
18f30 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
18f40 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
18f50 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
18f60 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
18f70 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
18f80 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
18f90 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
18fa0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
18fb0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
18fc0 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63  owid(D) interfac
18fd0 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e  e usually return
18fe0 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
18ff0 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63  .** the most rec
19000 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b  ent successful [
19010 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72  INSERT] into a r
19020 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76  owid table or [v
19030 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
19040 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e   on database con
19050 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65  nection D. ^Inse
19060 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55  rts into [WITHOU
19070 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20  T ROWID] tables 
19080 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72  are not.** recor
19090 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63  ded. ^If no succ
190a0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73  essful [INSERT]s
190b0 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c   into rowid tabl
190c0 65 73 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  es have ever occ
190d0 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65  urred .** on the
190e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
190f0 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c  tion D, then sql
19100 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
19110 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e  _rowid(D) return
19120 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  s .** zero..**.*
19130 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65 69  * As well as bei
19140 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69 63  ng set automatic
19150 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72 65  ally as rows are
19160 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 64   inserted into d
19170 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65  atabase.** table
19180 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
19190 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
191a0 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65  nction may be se
191b0 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79 0a  t explicitly by.
191c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
191d0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
191e0 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20  d()].**.** Some 
191f0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  virtual table im
19200 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61  plementations ma
19210 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69 6e  y INSERT rows in
19220 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20  to rowid tables 
19230 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f  as.** part of co
19240 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73  mmitting a trans
19250 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20  action (e.g. to 
19260 66 6c 75 73 68 20 64 61 74 61 20 61 63 63 75 6d  flush data accum
19270 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79  ulated in memory
19280 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e  .** to disk). In
19290 20 74 68 69 73 20 63 61 73 65 20 73 75 62 73 65   this case subse
192a0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74  quent calls to t
192b0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
192c0 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a  urn the rowid.**
192d0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
192e0 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c 20   these internal 
192f0 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f 6e  INSERT operation
19300 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20 74  s, which leads t
19310 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76  o .** unintuitiv
19320 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74 75  e results. Virtu
19330 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
19340 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64 6f  ntations that do
19350 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64 0a   write to rowid.
19360 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68 69  ** tables in thi
19370 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64 20  s way can avoid 
19380 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 20  this problem by 
19390 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f 72  restoring the or
193a0 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64  iginal .** rowid
193b0 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 71   value using [sq
193c0 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69  lite3_set_last_i
193d0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 62  nsert_rowid()] b
193e0 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20  efore returning 
193f0 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74  .** control to t
19400 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  he user..**.** ^
19410 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  (If an [INSERT] 
19420 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
19430 74 72 69 67 67 65 72 20 74 68 65 6e 20 74 68 69  trigger then thi
19440 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a  s routine will .
19450 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72  ** return the [r
19460 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73  owid] of the ins
19470 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e  erted row as lon
19480 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
19490 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e   is .** running.
194a0 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   Once the trigge
194b0 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20  r program ends, 
194c0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
194d0 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
194e0 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
194f0 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
19500 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
19510 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a   was fired.)^.**
19520 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
19530 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
19540 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
19550 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
19560 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
19570 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
19580 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
19590 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
195a0 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
195b0 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
195c0 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
195d0 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
195e0 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
195f0 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
19600 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
19610 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
19620 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
19630 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
19640 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
19650 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
19660 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
19670 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
19680 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
19690 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
196a0 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
196b0 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
196c0 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
196d0 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
196e0 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
196f0 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
19700 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
19710 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
19720 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
19730 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
19740 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
19750 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
19760 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
19770 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
19780 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
19790 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
197a0 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
197b0 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
197c0 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
197d0 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
197e0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
197f0 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
19800 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
19810 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
19820 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19830 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
19840 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
19850 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
19860 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
19870 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
19880 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
19890 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
198a0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
198b0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
198c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
198d0 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
198e0 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
198f0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
19900 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
19910 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
19920 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
19930 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
19940 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
19950 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
19960 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
19970 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
19980 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
19990 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65  owid]..*/.sqlite
199a0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
199b0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
199c0 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
199d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
199e0 74 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65 72  t the Last Inser
199f0 74 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a  t Rowid value..*
19a00 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
19a10 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  3.**.** The sqli
19a20 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73  te3_set_last_ins
19a30 65 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 20  ert_rowid(D, R) 
19a40 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68  method allows th
19a50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
19a60 0a 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c 75  .** set the valu
19a70 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 63 61  e returned by ca
19a80 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61  lling sqlite3_la
19a90 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
19aa0 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68  D) to R .** with
19ab0 6f 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61 20  out inserting a 
19ac0 72 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61 74  row into the dat
19ad0 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73  abase..*/.void s
19ae0 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f  qlite3_set_last_
19af0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
19b00 69 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  ite3*,sqlite3_in
19b10 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t64);../*.** CAP
19b20 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
19b30 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
19b40 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48  Modified.** METH
19b50 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
19b60 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
19b70 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
19b80 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
19b90 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  fied, inserted o
19ba0 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
19bb0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
19bc0 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
19bd0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
19be0 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
19bf0 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  t on the databas
19c00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65  e connection spe
19c10 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e  cified by the on
19c20 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ly parameter..**
19c30 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20   ^Executing any 
19c40 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51  other type of SQ
19c50 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
19c60 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20   not modify the 
19c70 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
19c80 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69  d by this functi
19c90 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  on..**.** ^Only 
19ca0 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72  changes made dir
19cb0 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53  ectly by the INS
19cc0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
19cd0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
19ce0 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
19cf0 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68  d - auxiliary ch
19d00 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
19d10 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
19d20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a  | triggers], .**
19d30 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
19d40 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41  tions] or [REPLA
19d50 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
19d60 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f  esolution are no
19d70 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
19d80 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76  * Changes to a v
19d90 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74  iew that are int
19da0 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20  ercepted by .** 
19db0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
19dc0 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46  ger | INSTEAD OF
19dd0 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e   triggers] are n
19de0 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65  ot counted. ^The
19df0 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72   value .** retur
19e00 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
19e10 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61  hanges() immedia
19e20 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e  tely after an IN
19e30 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
19e40 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65  .** DELETE state
19e50 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69  ment run on a vi
19e60 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  ew is always zer
19e70 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  o. Only changes 
19e80 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a  made to real .**
19e90 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e   tables are coun
19ea0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67  ted..**.** Thing
19eb0 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c  s are more compl
19ec0 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71  icated if the sq
19ed0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
19ee0 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65  function is.** e
19ef0 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20  xecuted while a 
19f00 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
19f10 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73  is running. This
19f20 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74   may happen if t
19f30 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  he.** program us
19f40 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  es the [changes(
19f50 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c  ) SQL function],
19f60 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65   or if some othe
19f70 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  r callback.** fu
19f80 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73  nction invokes s
19f90 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
19fa0 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e   directly. Essen
19fb0 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c  tially:.** .** <
19fc0 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ul>.**   <li> ^(
19fd0 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20  Before entering 
19fe0 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
19ff0 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  m the value retu
1a000 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  rned by.**      
1a010 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65    sqlite3_change
1a020 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  s() function is 
1a030 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65  saved. After the
1a040 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1a050 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20   .**        has 
1a060 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72  finished, the or
1a070 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20  iginal value is 
1a080 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a  restored.)^.** .
1a090 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68  **   <li> ^(With
1a0a0 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  in a trigger pro
1a0b0 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54  gram each INSERT
1a0c0 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c  , UPDATE and DEL
1a0d0 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73  ETE .**        s
1a0e0 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68  tatement sets th
1a0f0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1a100 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
1a110 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ges() .**       
1a120 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e   upon completion
1a130 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63   as normal. Of c
1a140 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75  ourse, this valu
1a150 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75  e will not inclu
1a160 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e  de .**        an
1a170 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72  y changes perfor
1a180 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67  med by sub-trigg
1a190 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69  ers, as the sqli
1a1a0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a  te3_changes() .*
1a1b0 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77  *        value w
1a1c0 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64  ill be saved and
1a1d0 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20   restored after 
1a1e0 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72  each sub-trigger
1a1f0 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c   has run.)^.** <
1a200 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69  /ul>.** .** ^Thi
1a210 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20  s means that if 
1a220 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51  the changes() SQ
1a230 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73  L function (or s
1a240 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a  imilar) is used.
1a250 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ** by the first 
1a260 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1a270 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
1a280 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
1a290 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75  ger, it .** retu
1a2a0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73  rns the value as
1a2b0 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61   set when the ca
1a2c0 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  lling statement 
1a2d0 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e  began executing.
1a2e0 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73  .** ^If it is us
1a2f0 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
1a300 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73   or subsequent s
1a310 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69  uch statement wi
1a320 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a  thin a trigger .
1a330 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20  ** program, the 
1a340 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72  value returned r
1a350 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62  eflects the numb
1a360 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
1a370 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70  ied by the .** p
1a380 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20  revious INSERT, 
1a390 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
1a3a0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
1a3b0 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  n the same trigg
1a3c0 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  er..**.** See al
1a3d0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
1a3e0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
1a3f0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
1a400 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
1a410 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
1a420 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
1a430 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
1a440 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
1a450 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
1a460 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
1a470 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a480 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
1a490 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1a4a0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
1a4b0 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
1a4c0 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
1a4d0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
1a4e0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
1a4f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
1a500 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
1a510 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a520 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
1a530 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
1a540 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1a550 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  3.**.** ^This fu
1a560 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
1a570 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
1a580 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64  of rows inserted
1a590 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a  , modified or.**
1a5a0 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20   deleted by all 
1a5b0 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
1a5c0 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
1a5d0 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65  tatements comple
1a5e0 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ted.** since the
1a5f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a600 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c  tion was opened,
1a610 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65   including those
1a620 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20   executed as.** 
1a630 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20  part of trigger 
1a640 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75  programs. ^Execu
1a650 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74  ting any other t
1a660 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ype of SQL state
1a670 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ment.** does not
1a680 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75   affect the valu
1a690 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
1a6a0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1a6b0 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43  ges()..** .** ^C
1a6c0 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70  hanges made as p
1a6d0 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20  art of [foreign 
1a6e0 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65  key actions] are
1a6f0 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
1a700 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74  .** count, but t
1a710 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72  hose made as par
1a720 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e  t of REPLACE con
1a730 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
1a740 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e  on are.** not. ^
1a750 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
1a760 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
1a770 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41  cepted by INSTEA
1a780 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a  D OF triggers .*
1a790 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
1a7a0 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c  d..** .** See al
1a7b0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
1a7c0 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
1a7d0 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
1a7e0 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
1a7f0 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f  ma], and the [to
1a800 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51  tal_changes() SQ
1a810 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
1a820 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
1a830 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
1a840 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
1a850 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a860 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
1a870 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1a880 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
1a890 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
1a8a0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ue.** returned i
1a8b0 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
1a8c0 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
1a8d0 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
1a8e0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1a8f0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1a900 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
1a910 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
1a920 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d  nning Query.** M
1a930 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1a940 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
1a950 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
1a960 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
1a970 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
1a980 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
1a990 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
1a9a0 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
1a9b0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
1a9c0 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
1a9d0 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
1a9e0 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
1a9f0 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
1aa00 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
1aa10 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
1aa20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
1aa30 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
1aa40 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
1aa50 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
1aa60 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
1aa70 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
1aa80 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
1aa90 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
1aaa0 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
1aab0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
1aac0 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
1aad0 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
1aae0 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
1aaf0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
1ab00 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
1ab10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1ab20 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
1ab30 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
1ab40 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
1ab50 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1ab60 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
1ab70 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
1ab80 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
1ab90 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
1aba0 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
1abb0 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
1abc0 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
1abd0 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
1abe0 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
1abf0 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
1ac00 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
1ac10 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
1ac20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
1ac30 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
1ac40 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
1ac50 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
1ac60 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
1ac70 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
1ac80 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
1ac90 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
1aca0 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
1acb0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
1acc0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
1acd0 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
1ace0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
1acf0 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
1ad00 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
1ad10 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
1ad20 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
1ad30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1ad40 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
1ad50 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
1ad60 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
1ad70 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
1ad80 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
1ad90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1ada0 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
1adb0 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
1adc0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1add0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1ade0 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
1adf0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1ae00 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
1ae10 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
1ae20 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
1ae30 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
1ae40 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
1ae50 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
1ae60 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
1ae70 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1ae80 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
1ae90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1aea0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1aeb0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
1aec0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
1aed0 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
1aee0 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
1aef0 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
1af00 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1af10 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
1af20 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1af30 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
1af40 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
1af50 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
1af60 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
1af70 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
1af80 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
1af90 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1afa0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1afb0 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
1afc0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
1afd0 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a  all returns..*/.
1afe0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
1aff0 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
1b000 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b010 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
1b020 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
1b030 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
1b040 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1b050 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
1b060 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
1b070 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
1b080 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
1b090 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
1b0a0 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
1b0b0 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
1b0c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
1b0d0 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
1b0e0 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
1b0f0 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
1b100 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
1b110 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
1b120 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
1b130 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
1b140 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1b150 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
1b160 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
1b170 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
1b180 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
1b190 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
1b1a0 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
1b1b0 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
1b1c0 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
1b1d0 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
1b1e0 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
1b1f0 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
1b200 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
1b210 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
1b220 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
1b230 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
1b240 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
1b250 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
1b260 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
1b270 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
1b280 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
1b290 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
1b2a0 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
1b2b0 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
1b2c0 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
1b2d0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
1b2e0 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
1b2f0 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
1b300 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
1b310 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
1b320 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
1b330 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
1b340 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1b350 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
1b360 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
1b370 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
1b380 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
1b390 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
1b3a0 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
1b3b0 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
1b3c0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
1b3d0 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
1b3e0 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
1b3f0 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
1b400 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
1b410 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
1b420 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
1b430 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
1b440 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
1b450 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
1b460 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
1b470 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
1b480 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
1b490 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
1b4a0 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
1b4b0 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
1b4c0 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
1b4d0 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
1b4e0 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
1b4f0 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
1b500 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
1b510 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
1b520 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
1b530 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
1b540 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
1b550 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
1b560 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1b570 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
1b580 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
1b590 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
1b5a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
1b5b0 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] 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 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
1b5e0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
1b5f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
1b600 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
1b610 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
1b620 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
1b630 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
1b640 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
1b650 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
1b660 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
1b670 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
1b680 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
1b690 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
1b6a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1b6b0 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
1b6c0 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
1b6d0 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
1b6e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75  ** KEYWORDS: {bu
1b6f0 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
1b700 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c  ack} {busy handl
1b710 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  er}.** METHOD: s
1b720 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1b730 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
1b740 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f  andler(D,X,P) ro
1b750 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
1b760 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
1b770 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62  .** that might b
1b780 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  e invoked with a
1b790 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76  rgument P whenev
1b7a0 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
1b7b0 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
1b7c0 73 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61  ss a database ta
1b7d0 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77  ble associated w
1b7e0 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ith.** [database
1b7f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77   connection] D w
1b800 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hen another thre
1b810 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
1b820 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c   has the table l
1b830 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71  ocked..** The sq
1b840 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1b850 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  er() interface i
1b860 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
1b870 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ent.** [sqlite3_
1b880 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
1b890 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79  and [PRAGMA busy
1b8a0 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a  _timeout]..**.**
1b8b0 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
1b8c0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
1b8d0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
1b8e0 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  Y].** is returne
1b8f0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
1b900 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
1b910 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74  the lock.  ^If t
1b920 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1b930 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  .** is not NULL,
1b940 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   then the callba
1b950 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  ck might be invo
1b960 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
1b970 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  uments..**.** ^T
1b980 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1b990 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61  t to the busy ha
1b9a0 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
1b9b0 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
1b9c0 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
1b9d0 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
1b9e0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
1b9f0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
1ba00 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
1ba10 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62  ment to.** the b
1ba20 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
1ba30 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
1ba40 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
1ba50 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1ba60 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
1ba70 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79  voked previously
1ba80 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f   for the same lo
1ba90 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
1baa0 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
1bab0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
1bac0 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
1bad0 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
1bae0 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
1baf0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
1bb00 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
1bb10 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a  Y] is returned.*
1bb20 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
1bb30 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
1bb40 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1bb50 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
1bb60 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
1bb70 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61  .** is made to a
1bb80 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
1bb90 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  se and the cycle
1bba0 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
1bbb0 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
1bbc0 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
1bbd0 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
1bbe0 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
1bbf0 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
1bc00 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
1bc10 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
1bc20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
1bc30 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
1bc40 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
1bc50 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
1bc60 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
1bc70 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
1bc80 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
1bc90 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20  ITE_BUSY].** to 
1bca0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1bcb0 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
1bcc0 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79  ing the .** busy
1bcd0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
1bce0 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
1bcf0 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
1bd00 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
1bd10 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
1bd20 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
1bd30 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
1bd40 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
1bd50 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
1bd60 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
1bd70 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
1bd80 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
1bd90 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
1bda0 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
1bdb0 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
1bdc0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
1bdd0 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
1bde0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
1bdf0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
1be00 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
1be10 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
1be20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
1be30 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
1be40 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
1be50 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
1be60 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
1be70 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
1be80 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
1be90 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
1bea0 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
1beb0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
1bec0 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
1bed0 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
1bee0 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
1bef0 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
1bf00 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1bf10 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
1bf20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
1bf30 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
1bf40 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
1bf50 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
1bf60 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
1bf70 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
1bf80 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1bf90 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1bfa0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1bfb0 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
1bfc0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1bfd0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
1bfe0 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
1bff0 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
1c000 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
1c010 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
1c020 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
1c030 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1c040 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f  _timeout()].** o
1c050 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52  r evaluating [PR
1c060 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1c070 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65  t=N] will change
1c080 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e   the.** busy han
1c090 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c  dler and thus cl
1c0a0 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73  ear any previous
1c0b0 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64  ly set busy hand
1c0c0 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
1c0d0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
1c0e0 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
1c0f0 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
1c100 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
1c110 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c120 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1c130 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
1c140 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
1c150 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
1c160 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e  dler is not reen
1c170 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68  trant.  Any such
1c180 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
1c190 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
1c1a0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
1c1b0 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
1c1c0 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
1c1d0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1c1e0 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72  ection.** or [pr
1c1f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1c200 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
1c210 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1c220 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1c230 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
1c240 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69  ite3*,int(*)(voi
1c250 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a  d*,int),void*);.
1c260 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c270 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
1c280 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  out.** METHOD: s
1c290 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1c2a0 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
1c2b0 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
1c2c0 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
1c2d0 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
1c2e0 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
1c2f0 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
1c300 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
1c310 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
1c320 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
1c330 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
1c340 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
1c350 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1c360 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1c370 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
1c380 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
1c390 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
1c3a0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1c3b0 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
1c3c0 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
1c3d0 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
1c3e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1c3f0 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
1c400 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
1c410 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69  .** ^Calling thi
1c420 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
1c430 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
1c440 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
1c450 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
1c460 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
1c470 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lers..**.** ^(Th
1c480 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
1c490 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
1c4a0 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
1c4b0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1c4c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1c4d0 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  at any given mom
1c4e0 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
1c4f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
1c500 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
1c510 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
1c520 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
1c530 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
1c540 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
1c550 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
1c560 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
1c570 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  red.)^.**.** See
1c580 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20   also:  [PRAGMA 
1c590 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f  busy_timeout].*/
1c5a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
1c5b0 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
1c5c0 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
1c5d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1c5e0 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
1c5f0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
1c600 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  ueries.** METHOD
1c610 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1c620 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79  This is a legacy
1c630 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
1c640 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72  is preserved for
1c650 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1c660 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65  tibility..** Use
1c670 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
1c680 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d  ce is not recomm
1c690 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66  ended..**.** Def
1c6a0 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
1c6b0 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
1c6c0 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
1c6d0 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
1c6e0 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
1c6f0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
1c700 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
1c710 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
1c720 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
1c730 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
1c740 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
1c750 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
1c760 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
1c770 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
1c780 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
1c790 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
1c7a0 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
1c7b0 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
1c7c0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1c7d0 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
1c7e0 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
1c7f0 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
1c800 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
1c810 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1c820 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
1c830 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1c840 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
1c850 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
1c860 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
1c870 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
1c880 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
1c890 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
1c8a0 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
1c8b0 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
1c8c0 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
1c8d0 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
1c8e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1c8f0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
1c900 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
1c910 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
1c920 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
1c930 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
1c940 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
1c950 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
1c960 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
1c970 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
1c980 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
1c990 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
1c9a0 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
1c9b0 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
1c9c0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
1c9d0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1c9e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
1c9f0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
1ca00 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
1ca10 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
1ca20 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
1ca30 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
1ca40 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
1ca50 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
1ca60 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
1ca70 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1ca80 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
1ca90 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
1caa0 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
1cab0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1cac0 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ble()]..**.** ^(
1cad0 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
1cae0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1caf0 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
1cb00 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
1cb10 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
1cb20 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1cb30 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1cb40 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
1cb50 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
1cb60 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
1cb70 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
1cb80 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
1cb90 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
1cba0 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
1cbb0 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
1cbc0 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
1cbd0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1cbe0 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
1cbf0 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
1cc00 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
1cc10 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
1cc20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
1cc30 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
1cc40 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
1cc50 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1cc60 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
1cc70 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
1cc80 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
1cc90 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
1cca0 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
1ccb0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1ccc0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1ccd0 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
1cce0 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
1ccf0 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
1cd00 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
1cd10 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
1cd20 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
1cd30 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1cd40 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
1cd50 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1cd60 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
1cd70 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1cd80 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
1cd90 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
1cda0 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
1cdb0 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
1cdc0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1cdd0 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
1cde0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1cdf0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1ce00 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1ce10 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
1ce20 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
1ce30 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
1ce40 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
1ce50 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
1ce60 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1ce70 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
1ce80 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
1ce90 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
1cea0 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
1ceb0 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
1cec0 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
1ced0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
1cee0 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70  ** After the app
1cef0 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e  lication has fin
1cf00 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72  ished with the r
1cf10 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74  esult from sqlit
1cf20 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a  e3_get_table(),.
1cf30 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20  ** it must pass 
1cf40 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1cf50 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
1cf60 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1cf70 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
1cf80 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1cf90 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c  ry that was mall
1cfa0 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  oced.  Because o
1cfb0 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a  f the way the.**
1cfc0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1cfd0 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
1cfe0 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
1cff0 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
1d000 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
1d010 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
1d020 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
1d030 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
1d040 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65   Only.** [sqlite
1d050 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
1d060 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
1d070 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
1d080 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
1d090 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
1d0a0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1d0b0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d   interface is im
1d0c0 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77  plemented as a w
1d0d0 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
1d0e0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1d0f0 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ].  The sqlite3_
1d100 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74  get_table() rout
1d110 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  ine does not hav
1d120 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61  e access.** to a
1d130 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ny internal data
1d140 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53   structures of S
1d150 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20  QLite.  It uses 
1d160 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a  only the public.
1d170 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66  ** interface def
1d180 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61  ined here.  As a
1d190 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72   consequence, er
1d1a0 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
1d1b0 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65  in the.** wrappe
1d1c0 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20  r layer outside 
1d1d0 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  of the internal 
1d1e0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1d1f0 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a   call are not.**
1d200 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75   reflected in su
1d210 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
1d220 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
1d230 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  de()] or.** [sql
1d240 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
1d250 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
1d260 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
1d270 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1d280 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
1d290 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
1d2a0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1d2b0 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
1d2c0 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
1d2d0 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
1d2e0 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
1d2f0 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
1d300 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
1d310 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1d320 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
1d330 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1d340 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
1d350 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1d360 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
1d370 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
1d380 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
1d390 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
1d3a0 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
1d3b0 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20  here */.);.void 
1d3c0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1d3d0 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
1d3e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d3f0 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
1d400 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
1d410 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1d420 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1d430 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
1d440 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
1d450 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
1d460 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
1d470 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1d480 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  y..** These rout
1d490 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20  ines understand 
1d4a0 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d  most of the comm
1d4b0 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e  on K&R formattin
1d4c0 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c  g options,.** pl
1d4d0 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  us some addition
1d4e0 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20  al non-standard 
1d4f0 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65  formats, detaile
1d500 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65  d below..** Note
1d510 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68   that some of th
1d520 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66  e more obscure f
1d530 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1d540 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a  s from recent.**
1d550 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64   C-library stand
1d560 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64  ards are omitted
1d570 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65   from this imple
1d580 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  mentation..**.**
1d590 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70   ^The sqlite3_mp
1d5a0 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
1d5b0 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
1d5c0 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
1d5d0 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
1d5e0 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
1d5f0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
1d600 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20  3_malloc()]..** 
1d610 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
1d620 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
1d630 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
1d640 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
1d650 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
1d660 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75  e()].  ^Both rou
1d670 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
1d680 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
1d690 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1d6a0 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74  c()] is unable t
1d6b0 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67  o allocate enoug
1d6c0 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68  h.** memory to h
1d6d0 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e  old the resultin
1d6e0 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  g string..**.** 
1d6f0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e  ^(The sqlite3_sn
1d700 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1d710 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
1d720 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
1d730 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
1d740 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
1d750 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
1d760 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
1d770 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
1d780 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1d790 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
1d7a0 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
1d7b0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1d7c0 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
1d7d0 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
1d7e0 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
1d7f0 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
1d800 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
1d810 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73  tf().)^  This is
1d820 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61   an.** historica
1d830 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20  l accident that 
1d840 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20  cannot be fixed 
1d850 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1d860 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
1d870 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28  mpatibility.  ^(
1d880 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
1d890 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1d8a0 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
1d8b0 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
1d8c0 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
1d8d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
1d8e0 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
1d8f0 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
1d900 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20  o the buffer.)^ 
1d910 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
1d920 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
1d930 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
1d940 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
1d950 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
1d960 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
1d970 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
1d980 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
1d990 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1d9a0 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
1d9b0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
1d9c0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1d9d0 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73  *.** ^As long as
1d9e0 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
1d9f0 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
1da00 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
1da10 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
1da20 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
1da30 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
1da40 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
1da50 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a  d.  ^The first.*
1da60 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
1da70 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
1da80 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
1da90 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
1daa0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
1dab0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
1dac0 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
1dad0 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
1dae0 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
1daf0 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
1db00 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
1db10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1db20 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  _vsnprintf() rou
1db30 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67  tine is a vararg
1db40 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c  s version of sql
1db50 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e  ite3_snprintf().
1db60 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1db70 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
1db80 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
1db90 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
1dba0 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
1dbb0 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
1dbc0 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
1dbd0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
1dbe0 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
1dbf0 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
1dc00 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
1dc10 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
1dc20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
1dc30 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22  "%q", "%Q", "%w"
1dc40 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
1dc50 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
1dc60 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
1dc70 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
1dc80 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
1dc90 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
1dca0 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
1dcb0 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
1dcc0 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
1dcd0 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
1dce0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
1dcf0 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
1dd00 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
1dd10 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
1dd20 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
1dd30 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
1dd40 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
1dd50 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
1dd60 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
1dd70 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
1dd80 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
1dd90 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
1dda0 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
1ddb0 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
1ddc0 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
1ddd0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1dde0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1ddf0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1de00 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
1de10 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
1de20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1de30 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
1de40 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
1de50 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
1de60 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
1de70 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1de80 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1de90 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1dea0 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1deb0 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1dec0 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
1ded0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1dee0 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1def0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1df00 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1df10 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1df20 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
1df30 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
1df40 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
1df50 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
1df60 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
1df70 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
1df80 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
1df90 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
1dfa0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1dfb0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
1dfc0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
1dfd0 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
1dfe0 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
1dff0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1e000 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
1e010 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
1e020 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
1e030 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
1e040 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
1e050 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
1e060 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
1e070 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1e080 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1e090 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1e0a0 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
1e0b0 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
1e0c0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1e0d0 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
1e0e0 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
1e0f0 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
1e100 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
1e110 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
1e120 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
1e130 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
1e140 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
1e150 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
1e160 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
1e170 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
1e180 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
1e190 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
1e1a0 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
1e1b0 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
1e1c0 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
1e1d0 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
1e1e0 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
1e1f0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
1e200 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
1e210 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
1e220 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
1e230 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
1e240 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
1e250 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
1e260 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
1e270 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
1e280 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
1e290 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1e2a0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1e2b0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1e2c0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1e2d0 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
1e2e0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1e2f0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1e300 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1e310 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1e320 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1e330 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1e340 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
1e350 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
1e360 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
1e370 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
1e380 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
1e390 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
1e3a0 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
1e3b0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
1e3c0 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74  The "%w" formatt
1e3d0 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69  ing option is li
1e3e0 6b 65 20 22 25 71 22 20 65 78 63 65 70 74 20 74  ke "%q" except t
1e3f0 68 61 74 20 69 74 20 65 78 70 65 63 74 73 20 74  hat it expects t
1e400 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65  o.** be containe
1e410 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d  d within double-
1e420 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f  quotes instead o
1e430 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c  f single quotes,
1e440 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70   and it.** escap
1e450 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75  es the double-qu
1e460 6f 74 65 20 63 68 61 72 61 63 74 65 72 20 69 6e  ote character in
1e470 73 74 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e  stead of the sin
1e480 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61  gle-quote.** cha
1e490 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22  racter.)^  The "
1e4a0 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %w" formatting o
1e4b0 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65  ption is intende
1e4c0 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73  d for safely ins
1e4d0 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20  erting.** table 
1e4e0 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73  and column names
1e4f0 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63   into a construc
1e500 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1e510 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  t..**.** ^(The "
1e520 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
1e530 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1e540 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74   "%s" but with t
1e550 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
1e560 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
1e570 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
1e580 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
1e590 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
1e5a0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1e5b0 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
1e5c0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1e5d0 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c  .)^.*/.char *sql
1e5e0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
1e5f0 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63  st char*,...);.c
1e600 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
1e610 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
1e620 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61  *, va_list);.cha
1e630 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
1e640 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1e650 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
1e660 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
1e670 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1e680 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1e690 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a  va_list);../*.**
1e6a0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1e6b0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
1e6c0 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65  system.**.** The
1e6d0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
1e6e0 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
1e6f0 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
1e700 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
1e710 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
1e720 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
1e730 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
1e740 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
1e750 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
1e760 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
1e770 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
1e780 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1e790 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
1e7a0 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
1e7b0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1e7c0 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
1e7d0 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
1e7e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
1e7f0 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
1e800 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1e810 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
1e820 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
1e830 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
1e840 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
1e850 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
1e860 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
1e870 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
1e880 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
1e890 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
1e8a0 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
1e8b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1e8c0 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74   ^If the paramet
1e8d0 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
1e8e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
1e8f0 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
1e900 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
1e910 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
1e920 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1e930 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1e940 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20  te3_malloc64(N) 
1e950 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75  routine works ju
1e960 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74  st like.** sqlit
1e970 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63  e3_malloc(N) exc
1e980 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e  ept that N is an
1e990 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74   unsigned 64-bit
1e9a0 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64   integer instead
1e9b0 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20  .** of a signed 
1e9c0 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a  32-bit integer..
1e9d0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
1e9e0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
1e9f0 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
1ea00 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
1ea10 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
1ea20 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1ea30 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
1ea40 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
1ea50 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
1ea60 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
1ea70 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
1ea80 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
1ea90 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
1eaa0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1eab0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
1eac0 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
1ead0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
1eae0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
1eaf0 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
1eb00 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
1eb10 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
1eb20 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
1eb30 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
1eb40 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
1eb50 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
1eb60 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
1eb70 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
1eb80 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
1eb90 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
1eba0 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
1ebb0 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
1ebc0 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
1ebd0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1ebe0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
1ebf0 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
1ec00 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
1ec10 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
1ec20 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
1ec30 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
1ec40 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1ec50 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1ec60 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
1ec70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
1ec80 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66  lloc(X,N) interf
1ec90 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
1eca0 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
1ecb0 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
1ecc0 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c  ion X to be at l
1ecd0 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a  east N bytes..**
1ece0 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d   ^If the X param
1ecf0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1ed00 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20  realloc(X,N).** 
1ed10 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1ed20 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
1ed30 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
1ed40 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
1ed50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1ed60 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70  ..** ^If the N p
1ed70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1ed80 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1ed90 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
1eda0 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
1edb0 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
1edc0 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
1edd0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1ede0 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20  te3_free(X)..** 
1edf0 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
1ee00 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20  (X,N) returns a 
1ee10 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
1ee20 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
1ee30 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
1ee40 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
1ee50 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69   NULL if insuffi
1ee60 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
1ee70 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49  available..** ^I
1ee80 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
1ee90 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1eea0 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
1eeb0 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
1eec0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1eed0 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
1eee0 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
1eef0 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
1ef00 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1ef10 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1ef20 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  ,N) and the prio
1ef30 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1ef40 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
1ef50 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1ef60 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  N) returns NULL 
1ef70 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76  and N is positiv
1ef80 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70  e, then the.** p
1ef90 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1efa0 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
1efb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1efc0 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20  _realloc64(X,N) 
1efd0 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73  interfaces works
1efe0 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20   the same as.** 
1eff0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f000 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74  X,N) except that
1f010 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75   N is a 64-bit u
1f020 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
1f030 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1f040 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
1f050 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  teger..**.** ^If
1f060 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61   X is a memory a
1f070 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f  llocation previo
1f080 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
1f090 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1f0a0 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c(),.** sqlite3_
1f0b0 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69  malloc64(), sqli
1f0c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f  te3_realloc(), o
1f0d0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1f0e0 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73  c64(), then.** s
1f0f0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1f100 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  returns the size
1f110 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20   of that memory 
1f120 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79  allocation in by
1f130 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  tes..** ^The val
1f140 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1f150 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1f160 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20  might be larger 
1f170 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a  than the number.
1f180 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75  ** of bytes requ
1f190 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73  ested when X was
1f1a0 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66   allocated.  ^If
1f1b0 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   X is a NULL poi
1f1c0 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  nter then.** sql
1f1d0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
1f1e0 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20  turns zero.  If 
1f1f0 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65  X points to some
1f200 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f  thing that is no
1f210 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69  t.** the beginni
1f220 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  ng of memory all
1f230 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69  ocation, or if i
1f240 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f  t points to a fo
1f250 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20  rmerly.** valid 
1f260 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1f270 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62  n that has now b
1f280 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20  een freed, then 
1f290 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
1f2a0 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  of sqlite3_msize
1f2b0 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  (X) is undefined
1f2c0 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61   and possibly ha
1f2d0 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rmful..**.** ^Th
1f2e0 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
1f2f0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
1f300 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  loc(), sqlite3_r
1f310 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  ealloc(),.** sql
1f320 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
1f330 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
1f340 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61  lloc64().** is a
1f350 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
1f360 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
1f370 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
1f380 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
1f390 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
1f3a0 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
1f3b0 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
1f3c0 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
1f3d0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
1f3e0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
1f3f0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
1f400 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
1f410 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
1f420 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
1f430 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
1f440 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
1f450 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
1f460 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
1f470 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
1f480 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
1f490 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
1f4a0 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
1f4b0 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
1f4c0 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
1f4d0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1f4e0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
1f4f0 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
1f500 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1f510 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64  3.7.10, the Wind
1f520 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
1f530 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a   layer called.**
1f540 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
1f550 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1f560 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
1f570 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
1f580 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
1f590 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
1f5a0 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
1f5b0 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
1f5c0 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
1f5d0 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
1f5e0 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
1f5f0 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
1f600 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
1f610 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77  ocation errors w
1f620 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  ere detected, bu
1f630 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72  t.** they were r
1f640 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
1f650 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
1f660 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
1f670 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
1f680 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
1f690 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
1f6a0 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
1f6b0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1f6c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1f6d0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
1f6e0 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
1f6f0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
1f700 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
1f710 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
1f720 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1f730 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
1f740 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1f750 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
1f760 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
1f770 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
1f780 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
1f790 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
1f7a0 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
1f7b0 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
1f7c0 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
1f7d0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
1f7e0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1f7f0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
1f800 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1f810 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
1f820 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
1f830 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
1f840 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f  alloc64(sqlite3_
1f850 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73  uint64);.void *s
1f860 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
1f870 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
1f880 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
1f890 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74  c64(void*, sqlit
1f8a0 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64  e3_uint64);.void
1f8b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
1f8c0 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69  id*);.sqlite3_ui
1f8d0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69  nt64 sqlite3_msi
1f8e0 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ze(void*);../*.*
1f8f0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1f900 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
1f910 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
1f920 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
1f930 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
1f940 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
1f950 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
1f960 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
1f970 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
1f980 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
1f990 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1f9a0 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
1f9b0 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
1f9c0 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
1f9d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
1f9e0 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
1f9f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1fa00 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
1fa10 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1fa20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
1fa30 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
1fa40 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
1fa50 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
1fa60 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
1fa70 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1fa80 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1fa90 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1faa0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
1fab0 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
1fac0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1fad0 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
1fae0 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
1faf0 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
1fb00 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
1fb10 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1fb20 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1fb30 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1fb40 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1fb50 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
1fb60 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
1fb70 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
1fb80 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
1fb90 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1fba0 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
1fbb0 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
1fbc0 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
1fbd0 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
1fbe0 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
1fbf0 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
1fc00 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
1fc10 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
1fc20 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
1fc30 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
1fc40 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
1fc50 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
1fc60 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1fc70 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
1fc80 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1fc90 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1fca0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1fcb0 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
1fcc0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1fcd0 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1fce0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1fcf0 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
1fd00 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1fd10 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
1fd20 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
1fd30 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1fd40 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
1fd50 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1fd60 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1fd70 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
1fd80 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
1fd90 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
1fda0 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
1fdb0 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
1fdc0 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
1fdd0 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
1fde0 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
1fdf0 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
1fe00 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
1fe10 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
1fe20 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
1fe30 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
1fe40 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
1fe50 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
1fe60 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
1fe70 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
1fe80 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
1fe90 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
1fea0 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
1feb0 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
1fec0 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
1fed0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
1fee0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1fef0 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
1ff00 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
1ff10 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
1ff20 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
1ff30 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
1ff40 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
1ff50 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
1ff60 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
1ff70 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20  ffer P..** ^The 
1ff80 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  P parameter can 
1ff90 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
1ffa0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69  r..**.** ^If thi
1ffb0 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f  s routine has no
1ffc0 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c  t been previousl
1ffd0 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74  y called or if t
1ffe0 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63  he previous.** c
1fff0 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74  all had N less t
20000 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c  han one or a NUL
20010 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c  L pointer for P,
20020 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69   then the PRNG i
20030 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e  s.** seeded usin
20040 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
20050 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78  ained from the x
20060 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
20070 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61  d of.** the defa
20080 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
20090 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66  ] object..** ^If
200a0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
200b0 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
200c0 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31  ne had an N of 1
200d0 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a   or more and a.*
200e0 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65  * non-NULL P the
200f0 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  n the pseudo-ran
20100 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
20110 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
20120 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
20130 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
20140 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
20150 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
20160 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  od..*/.void sqli
20170 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
20180 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
20190 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
201a0 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
201b0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
201c0 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  backs.** METHOD:
201d0 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57   sqlite3.** KEYW
201e0 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65  ORDS: {authorize
201f0 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a  r callback}.**.*
20200 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
20210 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74  registers an aut
20220 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20230 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
20240 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
20250 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
20260 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
20270 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
20280 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
20290 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
202a0 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
202b0 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
202c0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
202d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
202e0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
202f0 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
20300 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
20310 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20320 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
20330 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
20340 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a  .  ^At various.*
20350 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
20360 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
20370 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
20380 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
20390 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
203a0 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
203b0 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
203c0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
203d0 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
203e0 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
203f0 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54  are allowed.  ^T
20400 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
20410 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
20420 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
20430 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
20440 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
20450 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
20460 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
20470 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
20480 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
20490 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
204a0 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
204b0 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
204c0 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
204d0 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
204e0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
204f0 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
20500 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20   an error.  ^If 
20510 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
20520 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
20530 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
20540 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
20550 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
20560 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
20570 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
20580 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
20590 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
205a0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
205b0 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
205c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
205d0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
205e0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
205f0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
20600 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
20610 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
20620 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
20630 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
20640 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20  d is ok.  ^When 
20650 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
20660 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
20670 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
20680 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
20690 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
206a0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
206b0 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
206c0 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
206d0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
206e0 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
206f0 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
20700 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a  is denied. .**.*
20710 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
20720 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
20730 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20740 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
20750 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
20760 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
20770 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
20780 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
20790 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
207a0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
207b0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
207c0 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
207d0 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
207e0 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
207f0 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
20800 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
20810 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54  e authorized. ^T
20820 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
20830 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
20840 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
20850 62 61 63 6b 20 61 72 65 20 65 69 74 68 65 72 20  back are either 
20860 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6f 72  NULL pointers or
20870 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
20880 20 73 74 72 69 6e 67 73 0a 2a 2a 20 74 68 61 74   strings.** that
20890 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
208a0 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75  nal details abou
208b0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
208c0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
208d0 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d  * Applications m
208e0 75 73 74 20 61 6c 77 61 79 73 20 62 65 20 70 72  ust always be pr
208f0 65 70 61 72 65 64 20 74 6f 20 65 6e 63 6f 75 6e  epared to encoun
20900 74 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ter a NULL point
20910 65 72 20 69 6e 20 61 6e 79 0a 2a 2a 20 6f 66 20  er in any.** of 
20920 74 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  the third throug
20930 68 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61  h the sixth para
20940 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 61 75  meters of the au
20950 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c  thorization call
20960 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  back..**.** ^If 
20970 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
20980 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
20990 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
209a0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
209b0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
209c0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
209d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
209e0 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
209f0 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
20a00 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
20a10 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
20a20 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
20a30 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
20a40 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
20a50 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
20a60 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
20a70 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
20a80 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
20a90 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
20aa0 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
20ab0 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
20ac0 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
20ad0 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
20ae0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 74 61 62  ..** ^When a tab
20af0 6c 65 20 69 73 20 72 65 66 65 72 65 6e 63 65 64  le is referenced
20b00 20 62 79 20 61 20 5b 53 45 4c 45 43 54 5d 20 62   by a [SELECT] b
20b10 75 74 20 6e 6f 20 63 6f 6c 75 6d 6e 20 76 61 6c  ut no column val
20b20 75 65 73 20 61 72 65 0a 2a 2a 20 65 78 74 72 61  ues are.** extra
20b30 63 74 65 64 20 66 72 6f 6d 20 74 68 61 74 20 74  cted from that t
20b40 61 62 6c 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  able (for exampl
20b50 65 20 69 6e 20 61 20 71 75 65 72 79 20 6c 69 6b  e in a query lik
20b60 65 0a 2a 2a 20 22 53 45 4c 45 43 54 20 63 6f 75  e.** "SELECT cou
20b70 6e 74 28 2a 29 20 46 52 4f 4d 20 74 61 62 22 29  nt(*) FROM tab")
20b80 20 74 68 65 6e 20 74 68 65 20 5b 53 51 4c 49 54   then the [SQLIT
20b90 45 5f 52 45 41 44 5d 20 61 75 74 68 6f 72 69 7a  E_READ] authoriz
20ba0 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
20bb0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66  s invoked once f
20bc0 6f 72 20 74 68 61 74 20 74 61 62 6c 65 20 77 69  or that table wi
20bd0 74 68 20 61 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  th a column name
20be0 20 74 68 61 74 20 69 73 20 61 6e 20 65 6d 70 74   that is an empt
20bf0 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  y string..** ^If
20c00 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
20c10 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45   is [SQLITE_DELE
20c20 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  TE] and the call
20c30 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
20c40 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
20c50 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45  then the [DELETE
20c60 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  ] operation proc
20c70 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20  eeds but the.** 
20c80 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69  [truncate optimi
20c90 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62  zation] is disab
20ca0 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73  led and all rows
20cb0 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64   are deleted ind
20cc0 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  ividually..**.**
20cd0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
20ce0 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
20cf0 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
20d00 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
20d10 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
20d20 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f   an untrusted so
20d30 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
20d40 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
20d50 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f  tements.** do no
20d60 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
20d70 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f  data they are no
20d80 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
20d90 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
20da0 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20  o not.** try to 
20db0 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
20dc0 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
20dd0 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
20de0 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
20df0 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
20e00 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
20e10 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
20e20 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
20e30 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
20e40 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
20e50 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
20e60 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
20e70 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
20e80 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
20e90 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
20ea0 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
20eb0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
20ec0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
20ed0 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
20ee0 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
20ef0 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
20f00 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
20f10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20f20 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
20f30 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
20f40 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
20f50 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
20f60 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
20f70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
20f80 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
20f90 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
20fa0 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
20fb0 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
20fc0 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
20fd0 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
20fe0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
20ff0 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
21000 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
21010 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
21020 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
21030 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
21040 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
21050 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
21060 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65   ^(Only a single
21070 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
21080 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
21090 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
210a0 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
210b0 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
210c0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
210d0 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
210e0 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
210f0 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61  s call.)^  ^Disa
21100 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
21110 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
21120 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
21130 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
21140 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
21150 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
21160 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
21170 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
21180 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
21190 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
211a0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
211b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
211c0 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
211d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
211e0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
211f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21200 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
21210 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
21220 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
21230 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21240 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
21250 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
21260 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
21270 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b  h..**.** ^When [
21280 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21290 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  v2()] is used to
212a0 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65   prepare a state
212b0 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61  ment, the.** sta
212c0 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20  tement might be 
212d0 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69  re-prepared duri
212e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
212f0 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a  ()] due to a .**
21300 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20   schema change. 
21310 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c   Hence, the appl
21320 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65  ication should e
21330 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a  nsure that the.*
21340 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72  * correct author
21350 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
21360 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64  mains in place d
21370 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  uring the [sqlit
21380 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
21390 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  * ^Note that the
213a0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
213b0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
213c0 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b  only during.** [
213d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
213e0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
213f0 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
21400 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
21410 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
21420 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
21430 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
21440 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a  tep()], unless.*
21450 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74  * as stated in t
21460 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
21470 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73  graph, sqlite3_s
21480 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a  tep() invokes.**
21490 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
214a0 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61  _v2() to reprepa
214b0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61  re a statement a
214c0 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68  fter a schema ch
214d0 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ange..*/.int sql
214e0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
214f0 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
21500 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
21510 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
21520 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
21530 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
21540 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
21550 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
21560 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21570 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
21580 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
21590 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
215a0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
215b0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
215c0 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
215d0 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
215e0 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
215f0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
21600 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
21610 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
21620 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
21630 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
21640 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
21650 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
21660 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
21670 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
21680 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
21690 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
216a0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
216b0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
216c0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73  SQLITE_IGNORE is
216d0 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20   also used as a 
216e0 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75  [conflict resolu
216f0 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65  tion mode].** re
21700 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  turned from the 
21710 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
21720 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74  _conflict()] int
21730 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
21740 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
21750 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
21760 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
21770 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
21780 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21790 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
217a0 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
217b0 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
217c0 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
217d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
217e0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
217f0 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
21800 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
21810 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
21820 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
21830 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
21840 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
21850 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
21860 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
21870 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
21880 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
21890 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
218a0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
218b0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
218c0 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
218d0 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
218e0 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
218f0 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
21900 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
21910 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
21920 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
21930 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
21940 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
21950 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
21960 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
21970 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
21980 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
21990 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
219a0 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
219b0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
219c0 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
219d0 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
219e0 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
219f0 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
21a00 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
21a10 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
21a20 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
21a30 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
21a40 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20  ter.  ^(The 5th 
21a50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
21a60 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
21a70 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
21a80 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
21a90 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
21aa0 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
21ab0 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20   applicable.)^  
21ac0 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74  ^The 6th paramet
21ad0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
21ae0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
21af0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
21b00 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
21b10 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
21b20 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
21b30 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
21b40 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
21b50 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
21b60 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
21b70 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
21b80 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
21b90 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
21ba0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21bb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21bc0 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
21bd0 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
21be0 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
21bf0 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
21c00 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
21c10 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
21c20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
21c30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21c40 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
21c50 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
21c60 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21c70 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21c80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21c90 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
21ca0 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
21cb0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
21cc0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21cd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21ce0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
21cf0 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
21d00 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
21d10 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21d20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21d30 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
21d40 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
21d50 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
21d60 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
21d70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21d80 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
21d90 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
21da0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
21db0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21dc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21dd0 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
21de0 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
21df0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
21e00 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
21e10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
21e20 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
21e30 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
21e40 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
21e50 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21e60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
21e70 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
21e80 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
21e90 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
21ea0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21eb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21ec0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
21ed0 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
21ee0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
21ef0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
21f00 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
21f10 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
21f20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
21f30 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
21f40 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21f50 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
21f60 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
21f70 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
21f80 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
21f90 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21fa0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
21fb0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
21fc0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21fd0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21fe0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21ff0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
22000 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
22010 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
22020 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
22030 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22040 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
22050 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
22060 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
22070 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22080 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22090 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
220a0 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
220b0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
220c0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
220d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
220e0 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
220f0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
22100 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
22110 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22120 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22130 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
22140 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
22150 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22160 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22170 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22180 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
22190 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
221a0 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
221b0 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
221c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
221d0 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
221e0 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
221f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
22200 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
22210 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22220 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
22230 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
22240 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
22250 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22260 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22270 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
22280 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
22290 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
222a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
222b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
222c0 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
222d0 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
222e0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
222f0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
22300 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
22310 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
22320 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
22330 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
22340 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22350 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
22360 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
22370 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
22380 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
22390 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
223a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
223b0 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
223c0 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
223d0 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
223e0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
223f0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
22400 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
22410 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
22420 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22430 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22440 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
22450 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
22460 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
22470 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
22480 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22490 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
224a0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
224b0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
224c0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
224d0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
224e0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
224f0 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
22500 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22510 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
22520 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22530 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
22540 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
22550 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
22560 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
22570 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
22580 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
22590 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
225a0 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
225b0 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
225c0 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
225d0 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
225e0 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
225f0 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
22600 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22610 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20  TE_RECURSIVE    
22620 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20          33   /* 
22630 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22640 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22650 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
22660 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
22670 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
22680 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
22690 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
226a0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
226b0 64 65 70 72 65 63 61 74 65 64 2e 20 55 73 65 20  deprecated. Use 
226c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  the [sqlite3_tra
226d0 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  ce_v2()] interfa
226e0 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66  ce.** instead of
226f0 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20 64 65   the routines de
22700 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a  scribed here..**
22710 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
22720 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
22730 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
22740 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
22750 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
22760 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
22770 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
22780 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
22790 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
227a0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
227b0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
227c0 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
227d0 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
227e0 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
227f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
22800 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
22810 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
22820 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
22830 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
22840 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
22850 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
22860 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
22870 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
22880 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
22890 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
228a0 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
228b0 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
228c0 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
228d0 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
228e0 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
228f0 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
22900 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
22910 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
22920 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
22930 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
22940 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
22950 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
22960 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  r.)^.**.** The [
22970 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
22980 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
22990 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e  -time option can
229a0 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69   be used to limi
229b0 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20  t.** the length 
229c0 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  of [bound parame
229d0 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69  ter] expansion i
229e0 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  n the output of 
229f0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e  sqlite3_trace().
22a00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
22a10 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
22a20 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
22a30 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
22a40 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
22a50 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
22a60 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
22a70 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
22a80 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
22a90 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
22aa0 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
22ab0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
22ac0 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
22ad0 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
22ae0 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
22af0 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
22b00 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
22b10 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
22b20 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
22b30 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
22b40 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
22b50 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
22b60 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
22b70 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
22b80 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
22b90 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
22ba0 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
22bb0 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
22bc0 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
22bd0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
22be0 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
22bf0 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
22c00 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
22c10 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
22c20 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
22c30 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
22c40 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
22c50 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
22c60 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
22c70 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
22c80 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
22c90 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49   SQLite..*/.SQLI
22ca0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
22cb0 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
22cc0 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
22cd0 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
22ce0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
22cf0 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
22d00 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
22d10 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
22d20 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
22d30 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
22d40 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
22d50 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
22d60 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
22d70 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72  CAPI3REF: SQL Tr
22d80 61 63 65 20 45 76 65 6e 74 20 43 6f 64 65 73 0a  ace Event Codes.
22d90 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
22da0 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20  ITE_TRACE.**.** 
22db0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
22dc0 69 64 65 6e 74 69 66 79 20 63 6c 61 73 73 65 73  identify classes
22dd0 20 6f 66 20 65 76 65 6e 74 73 20 74 68 61 74 20   of events that 
22de0 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64  can be monitored
22df0 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 73  .** using the [s
22e00 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
22e10 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f 67 69 63  )] tracing logic
22e20 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
22e30 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c  ument.** to [sql
22e40 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
22e50 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d   is an OR-ed com
22e60 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20  bination of one 
22e70 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68  or more of.** th
22e80 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73  e following cons
22e90 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69 72  tants.  ^The fir
22ea0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
22eb0 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  he trace callbac
22ec0 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74  k.** is one of t
22ed0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e  he following con
22ee0 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65  stants..**.** Ne
22ef0 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74 61  w tracing consta
22f00 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  nts may be added
22f10 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
22f20 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72  ses..**.** ^A tr
22f30 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61 73  ace callback has
22f40 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a   four arguments:
22f50 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50   xCallback(T,C,P
22f60 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61  ,X)..** ^The T a
22f70 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
22f80 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 74 79  f the integer ty
22f90 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a  pe codes above..
22fa0 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65  ** ^The C argume
22fb0 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  nt is a copy of 
22fc0 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e  the context poin
22fd0 74 65 72 20 70 61 73 73 65 64 20 69 6e 20 61 73  ter passed in as
22fe0 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61   the.** fourth a
22ff0 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
23000 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e  te3_trace_v2()].
23010 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20  .** The P and X 
23020 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f  arguments are po
23030 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61  inters whose mea
23040 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20  nings depend on 
23050 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  T..**.** <dl>.**
23060 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f   [[SQLITE_TRACE_
23070 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  STMT]] <dt>SQLIT
23080 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74  E_TRACE_STMT</dt
23090 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
230a0 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 63  ITE_TRACE_STMT c
230b0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
230c0 65 64 20 77 68 65 6e 20 61 20 70 72 65 70 61 72  ed when a prepar
230d0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
230e0 66 69 72 73 74 20 62 65 67 69 6e 73 20 72 75 6e  first begins run
230f0 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62 6c  ning and possibl
23100 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65 73  y at other times
23110 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65   during the.** e
23120 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
23130 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23140 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74 20 74  nt, such as at t
23150 68 65 20 73 74 61 72 74 20 6f 66 20 65 61 63 68  he start of each
23160 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62 70  .** trigger subp
23170 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20 61  rogram. ^The P a
23180 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
23190 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  nter to the.** [
231a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
231b0 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67 75  nt]. ^The X argu
231c0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
231d0 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  r to a string wh
231e0 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e  ich.** is the un
231f0 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65 78  expanded SQL tex
23200 74 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65  t of the prepare
23210 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61  d statement or a
23220 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a  n SQL comment .*
23230 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  * that indicates
23240 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20   the invocation 
23250 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 5e  of a trigger.  ^
23260 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e  The callback can
23270 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20   compute.** the 
23280 73 61 6d 65 20 74 65 78 74 20 74 68 61 74 20 77  same text that w
23290 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20 72  ould have been r
232a0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 6c  eturned by the l
232b0 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 74  egacy [sqlite3_t
232c0 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  race()].** inter
232d0 66 61 63 65 20 62 79 20 75 73 69 6e 67 20 74 68  face by using th
232e0 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68 65  e X argument whe
232f0 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74 68 20  n X begins with 
23300 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  "--" and invokin
23310 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  g.** [sqlite3_ex
23320 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f  panded_sql(P)] o
23330 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
23340 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  [[SQLITE_TRACE_P
23350 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c  ROFILE]] <dt>SQL
23360 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
23370 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  E</dt>.** <dd>^A
23380 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  n SQLITE_TRACE_P
23390 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20  ROFILE callback 
233a0 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78 69  provides approxi
233b0 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65 0a  mately the same.
233c0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ** information a
233d0 73 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  s is provided by
233e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
233f0 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63  ofile()] callbac
23400 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67  k..** ^The P arg
23410 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
23420 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  er to the [prepa
23430 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
23440 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75  nd the.** X argu
23450 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
23460 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
23470 77 68 69 63 68 20 69 73 20 74 68 65 20 65 73 74  which is the est
23480 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65  imated of.** the
23490 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73   number of nanos
234a0 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20 70  econd that the p
234b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
234c0 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a  t took to run..*
234d0 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54 52  * ^The SQLITE_TR
234e0 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c  ACE_PROFILE call
234f0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
23500 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
23510 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a  nt finishes..**.
23520 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
23530 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49  E_ROW]] <dt>SQLI
23540 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74  TE_TRACE_ROW</dt
23550 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
23560 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63 61  ITE_TRACE_ROW ca
23570 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
23580 64 20 77 68 65 6e 65 76 65 72 20 61 20 70 72 65  d whenever a pre
23590 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
235a0 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61 20 73  nt generates a s
235b0 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65 73  ingle row of res
235c0 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50  ult.  .** ^The P
235d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
235e0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70  ointer to the [p
235f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23600 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20  t] and the.** X 
23610 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73  argument is unus
23620 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ed..**.** [[SQLI
23630 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d  TE_TRACE_CLOSE]]
23640 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
23650 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20  E_CLOSE</dt>.** 
23660 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
23670 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62  RACE_CLOSE callb
23680 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
23690 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hen a database.*
236a0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  * connection clo
236b0 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61  ses..** ^The P a
236c0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
236d0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
236e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
236f0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  ] object.** and 
23700 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69  the X argument i
23710 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64  s unused..** </d
23720 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
23730 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20  LITE_TRACE_STMT 
23740 20 20 20 20 20 20 30 78 30 31 0a 23 64 65 66 69        0x01.#defi
23750 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
23760 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32 0a  PROFILE    0x02.
23770 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
23780 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20 20  RACE_ROW        
23790 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x04.#define SQL
237a0 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20  ITE_TRACE_CLOSE 
237b0 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a       0x08../*.**
237c0 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54   CAPI3REF: SQL T
237d0 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54  race Hook.** MET
237e0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
237f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
23800 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50  trace_v2(D,M,X,P
23810 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
23820 73 74 65 72 73 20 61 20 74 72 61 63 65 20 63 61  sters a trace ca
23830 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
23840 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64 61  on X against [da
23850 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23860 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f 70  n] D, using prop
23870 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61  erty mask M.** a
23880 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74  nd context point
23890 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20 58  er P.  ^If the X
238a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20   callback is.** 
238b0 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20 4d  NULL or if the M
238c0 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74   mask is zero, t
238d0 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20 64  hen tracing is d
238e0 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a  isabled.  The.**
238f0 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75   M argument shou
23900 6c 64 20 62 65 20 74 68 65 20 62 69 74 77 69 73  ld be the bitwis
23910 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74  e OR-ed combinat
23920 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f  ion of.** zero o
23930 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54  r more [SQLITE_T
23940 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e  RACE] constants.
23950 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c  .**.** ^Each cal
23960 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c 69  l to either sqli
23970 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73  te3_trace() or s
23980 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
23990 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a 20  ) overrides .** 
239a0 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70 72  (cancels) any pr
239b0 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ior calls to sql
239c0 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20  ite3_trace() or 
239d0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
239e0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58  ()..**.** ^The X
239f0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
23a00 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
23a10 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73 20  y of the events 
23a20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a 2a  identified by .*
23a30 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20  * mask M occur. 
23a40 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72 65   ^The integer re
23a50 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
23a60 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
23a70 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e  currently.** ign
23a80 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68 69  ored, though thi
23a90 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e 20  s may change in 
23aa0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
23ab0 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d    Callback.** im
23ac0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
23ad0 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72 6f  ould return zero
23ae0 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75 72   to ensure futur
23af0 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  e compatibility.
23b00 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20  .**.** ^A trace 
23b10 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
23b20 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20 61 72  ked with four ar
23b30 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63  guments: callbac
23b40 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e  k(T,C,P,X)..** ^
23b50 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69  The T argument i
23b60 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53 51  s one of the [SQ
23b70 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63  LITE_TRACE].** c
23b80 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64 69  onstants to indi
23b90 63 61 74 65 20 77 68 79 20 74 68 65 20 63 61 6c  cate why the cal
23ba0 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65  lback was invoke
23bb0 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67  d..** ^The C arg
23bc0 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20  ument is a copy 
23bd0 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70  of the context p
23be0 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50  ointer..** The P
23bf0 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73   and X arguments
23c00 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68   are pointers wh
23c10 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70  ose meanings dep
23c20 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20  end on T..**.** 
23c30 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
23c40 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
23c50 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
23c60 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67 61  replace the lega
23c70 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
23c80 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
23c90 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
23ca0 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68  profile()], both
23cb0 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72 65   of which.** are
23cc0 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a   deprecated..*/.
23cd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 63  int sqlite3_trac
23ce0 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  e_v2(.  sqlite3*
23cf0 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d 61  ,.  unsigned uMa
23d00 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c  sk,.  int(*xCall
23d10 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76  back)(unsigned,v
23d20 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a  oid*,void*,void*
23d30 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78 0a  ),.  void *pCtx.
23d40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23d50 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
23d60 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  ss Callbacks.** 
23d70 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
23d80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
23d90 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
23da0 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
23db0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
23dc0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
23dd0 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
23de0 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
23df0 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
23e00 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
23e10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
23e20 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
23e30 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
23e40 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
23e50 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
23e60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
23e70 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
23e80 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
23e90 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
23ea0 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
23eb0 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
23ec0 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
23ed0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
23ee0 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
23ef0 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
23f00 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
23f10 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
23f20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
23f30 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72  er N is the appr
23f40 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f  oximate number o
23f50 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
23f60 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
23f70 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
23f80 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
23f90 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
23fa0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
23fb0 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49   callback X.  ^I
23fc0 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
23fd0 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72   one then the pr
23fe0 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65  ogress.** handle
23ff0 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  r is disabled..*
24000 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
24010 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
24020 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
24030 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
24040 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
24050 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
24060 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
24070 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
24080 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
24090 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
240a0 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
240b0 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
240c0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
240d0 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
240e0 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
240f0 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
24100 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
24110 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
24120 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
24130 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
24140 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
24150 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
24160 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
24170 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
24180 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
24190 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
241a0 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
241b0 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
241c0 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
241d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
241e0 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
241f0 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
24200 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
24210 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
24220 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
24230 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
24240 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
24250 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
24260 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
24270 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
24280 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24290 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
242a0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
242b0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
242c0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
242d0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
242e0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
242f0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
24300 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
24310 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
24320 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
24330 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
24340 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
24350 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
24360 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54  nection.** CONST
24370 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a  RUCTOR: sqlite3.
24380 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
24390 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
243a0 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
243b0 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20  le as specified 
243c0 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e  by the .** filen
243d0 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
243e0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
243f0 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
24400 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
24410 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
24420 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
24430 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
24440 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
24450 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
24460 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
24470 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
24480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24490 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
244a0 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
244b0 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
244c0 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
244d0 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
244e0 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
244f0 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
24500 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
24510 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
24520 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
24530 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
24540 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
24550 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
24560 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
24570 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
24580 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
24590 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
245a0 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
245b0 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
245c0 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
245d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
245e0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
245f0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
24600 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
24610 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
24620 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
24630 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
24640 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
24650 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
24660 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
24670 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
24680 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
24690 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
246a0 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
246b0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
246c0 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
246d0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
246e0 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
246f0 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  g will be UTF-8 
24700 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72  for databases cr
24710 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73  eated using.** s
24720 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
24730 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
24740 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c  ().  ^The defaul
24750 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64  t encoding for d
24760 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61  atabases.** crea
24770 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ted using sqlite
24780 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20  3_open16() will 
24790 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  be UTF-16 in the
247a0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
247b0 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  er..**.** Whethe
247c0 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
247d0 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
247e0 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
247f0 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
24800 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
24810 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24820 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
24830 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
24840 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
24850 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
24860 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
24870 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
24880 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
24890 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
248a0 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
248b0 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
248c0 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
248d0 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
248e0 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
248f0 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
24900 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
24910 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
24920 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24930 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
24940 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
24950 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24960 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
24970 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
24980 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
24990 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
249a0 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
249b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
249c0 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
249d0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
249e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
249f0 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b  AREDCACHE],.** [
24a00 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
24a10 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f  ATECACHE], and/o
24a20 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  r [SQLITE_OPEN_U
24a30 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  RI] flags:)^.**.
24a40 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
24a50 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
24a60 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
24a70 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
24a80 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
24a90 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
24aa0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
24ab0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
24ac0 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
24ad0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
24ae0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
24af0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
24b00 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
24b10 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
24b20 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
24b30 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
24b40 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
24b50 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
24b60 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
24b70 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
24b80 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
24b90 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
24ba0 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
24bb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
24bc0 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
24bd0 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
24be0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
24bf0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
24c00 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
24c10 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
24c20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
24c30 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
24c40 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
24c50 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
24c60 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
24c70 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69  and is created i
24c80 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
24c90 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
24ca0 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
24cb0 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
24cc0 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
24cd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
24ce0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
24cf0 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
24d00 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
24d10 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
24d20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
24d30 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
24d40 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
24d50 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
24d60 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  ve optionally co
24d70 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65  mbined with othe
24d80 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  r.** [SQLITE_OPE
24d90 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c  N_READONLY | SQL
24da0 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d  ITE_OPEN_* bits]
24db0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
24dc0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
24dd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
24de0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
24df0 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
24e00 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
24e10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24e20 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
24e30 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
24e40 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
24e50 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
24e60 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
24e70 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
24e80 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
24e90 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
24ea0 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
24eb0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
24ec0 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
24ed0 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
24ee0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24ef0 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
24f00 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
24f10 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
24f20 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
24f30 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
24f40 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
24f50 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
24f60 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
24f70 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
24f80 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
24f90 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
24fa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24fb0 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
24fc0 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
24fd0 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
24fe0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
24ff0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
25000 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
25010 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
25020 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
25030 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
25040 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
25050 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
25060 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
25070 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
25080 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
25090 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
250a0 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
250b0 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
250c0 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
250d0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
250e0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
250f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
25100 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
25110 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
25120 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
25130 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
25140 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
25150 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
25160 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
25170 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
25180 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75  se.  ^If the fou
25190 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
251a0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
251b0 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
251c0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
251d0 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
251e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
251f0 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
25200 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
25210 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
25220 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
25230 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
25240 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
25250 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
25260 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
25270 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
25280 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
25290 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
252a0 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
252b0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
252c0 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
252d0 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
252e0 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
252f0 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
25300 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
25310 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
25320 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
25330 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
25340 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
25350 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
25360 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
25370 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
25380 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
25390 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
253a0 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
253b0 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
253c0 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
253d0 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
253e0 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
253f0 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
25400 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
25410 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
25420 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
25430 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
25440 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
25450 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
25460 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
25470 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
25480 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
25490 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
254a0 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   [[URI filenames
254b0 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
254c0 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c  ()]] <h3>URI Fil
254d0 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  enames</h3>.**.*
254e0 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e  * ^If [URI filen
254f0 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74  ame] interpretat
25500 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  ion is enabled, 
25510 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  and the filename
25520 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67   argument.** beg
25530 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22  ins with "file:"
25540 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e  , then the filen
25550 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74  ame is interpret
25560 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52  ed as a URI. ^UR
25570 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e  I.** filename in
25580 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
25590 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b  enabled if the [
255a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
255b0 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20   flag is.** set 
255c0 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  in the fourth ar
255d0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
255e0 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20  3_open_v2(), or 
255f0 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65  if it has.** bee
25600 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c  n enabled global
25610 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ly using the [SQ
25620 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
25630 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65   option with the
25640 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
25650 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72  fig()] method or
25660 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
25670 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65  USE_URI] compile
25680 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
25690 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65   As of SQLite ve
256a0 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49  rsion 3.7.7, URI
256b0 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
256c0 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e  retation is turn
256d0 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66  ed off.** by def
256e0 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65  ault, but future
256f0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
25700 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65  ite might enable
25710 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   URI filename.**
25720 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
25730 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65  by default.  See
25740 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   "[URI filenames
25750 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ]" for additiona
25760 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
25770 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65  ..**.** URI file
25780 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64  names are parsed
25790 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46   according to RF
257a0 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20  C 3986. ^If the 
257b0 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a  URI contains an.
257c0 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68  ** authority, th
257d0 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69  en it must be ei
257e0 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74  ther an empty st
257f0 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69  ring or the stri
25800 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73  ng .** "localhos
25810 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68  t". ^If the auth
25820 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20  ority is not an 
25830 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
25840 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20  "localhost", an 
25850 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74  .** error is ret
25860 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c  urned to the cal
25870 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65  ler. ^The fragme
25880 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  nt component of 
25890 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72  a URI, if .** pr
258a0 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65  esent, is ignore
258b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
258c0 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63   uses the path c
258d0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20  omponent of the 
258e0 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20  URI as the name 
258f0 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65  of the disk file
25900 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69  .** which contai
25910 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ns the database.
25920 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65   ^If the path be
25930 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20  gins with a '/' 
25940 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74  character, .** t
25950 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70  hen it is interp
25960 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f  reted as an abso
25970 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74  lute path. ^If t
25980 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74  he path does not
25990 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20   begin .** with 
259a0 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74  a '/' (meaning t
259b0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74  hat the authorit
259c0 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69  y section is omi
259d0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52  tted from the UR
259e0 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70  I).** then the p
259f0 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ath is interpret
25a00 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65  ed as a relative
25a10 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20   path. .** ^(On 
25a20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72  windows, the fir
25a30 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  st component of 
25a40 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
25a50 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20   .** is a drive 
25a60 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65  specification (e
25a70 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a  .g. "C:").)^.**.
25a80 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75  ** [[core URI qu
25a90 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d  ery parameters]]
25aa0 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f  .** The query co
25ab0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
25ac0 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72   may contain par
25ad0 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
25ae0 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20   interpreted.** 
25af0 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65  either by SQLite
25b00 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61   itself, or by a
25b10 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56   [VFS | custom V
25b20 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
25b30 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e  n]..** SQLite an
25b40 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b  d its built-in [
25b50 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74  VFSes] interpret
25b60 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   the.** followin
25b70 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  g query paramete
25b80 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  rs:.**.** <ul>.*
25b90 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c  *   <li> <b>vfs<
25ba0 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20  /b>: ^The "vfs" 
25bb0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
25bc0 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79   used to specify
25bd0 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20   the name of.** 
25be0 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74      a VFS object
25bf0 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74   that provides t
25c00 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
25c10 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
25c20 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20  at should.**    
25c30 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65   be used to acce
25c40 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
25c50 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49  file on disk. ^I
25c60 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  f this option is
25c70 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61   set to.**     a
25c80 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74  n empty string t
25c90 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f  he default VFS o
25ca0 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e  bject is used. ^
25cb0 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
25cc0 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53  known.**     VFS
25cd0 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49   is an error. ^I
25ce0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
25cf0 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
25d00 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69  the vfs option i
25d10 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74  s.**     present
25d20 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73  , then the VFS s
25d30 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
25d40 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65  option takes pre
25d50 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20  cedence over.** 
25d60 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61      the value pa
25d70 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
25d80 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
25d90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25da0 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
25db0 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54  <b>mode</b>: ^(T
25dc0 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
25dd0 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
25de0 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77  either "ro", "rw
25df0 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c  ",.**     "rwc",
25e00 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74   or "memory". At
25e10 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
25e20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20  it to any other 
25e30 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20  value is.**     
25e40 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20  an error)^. .** 
25e50 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20      ^If "ro" is 
25e60 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
25e70 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
25e80 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
25e90 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63  only .**     acc
25ea0 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20  ess, just as if 
25eb0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
25ec0 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20  _READONLY] flag 
25ed0 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20  had been set in 
25ee0 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72  the .**     thir
25ef0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
25f00 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
25f10 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
25f20 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a  tion is set to .
25f30 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65  **     "rw", the
25f40 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
25f50 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
25f60 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74  d-write (but not
25f70 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20   create) .**    
25f80 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53   access, as if S
25f90 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
25fa0 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51  RITE (but not SQ
25fb0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
25fc0 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65  ) had .**     be
25fd0 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22  en set. ^Value "
25fe0 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65  rwc" is equivale
25ff0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f  nt to setting bo
26000 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  th .**     SQLIT
26010 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
26020 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e   and SQLITE_OPEN
26030 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68  _CREATE.  ^If th
26040 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
26050 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22  .**     set to "
26060 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70  memory" then a p
26070 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64  ure [in-memory d
26080 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65  atabase] that ne
26090 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20  ver reads.**    
260a0 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20   or writes from 
260b0 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49  disk is used. ^I
260c0 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f  t is an error to
260d0 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65   specify a value
260e0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20   for.**     the 
260f0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74  mode parameter t
26100 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74  hat is less rest
26110 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61  rictive than tha
26120 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  t specified by.*
26130 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20  *     the flags 
26140 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68  passed in the th
26150 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
26160 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26170 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
26180 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e   <b>cache</b>: ^
26190 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  The cache parame
261a0 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
261b0 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64  o either "shared
261c0 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69  " or.**     "pri
261d0 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20  vate". ^Setting 
261e0 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69  it to "shared" i
261f0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
26200 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20  setting the.**  
26210 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53     SQLITE_OPEN_S
26220 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69  HAREDCACHE bit i
26230 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  n the flags argu
26240 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a  ment passed to.*
26250 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70  *     sqlite3_op
26260 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e  en_v2(). ^Settin
26270 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61  g the cache para
26280 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74  meter to "privat
26290 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71  e" is .**     eq
262a0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
262b0 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
262c0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
262d0 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66   bit..**     ^If
262e0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
262f0 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
26300 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d  he "cache" param
26310 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20  eter is present 
26320 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20  in.**     a URI 
26330 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61  filename, its va
26340 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e  lue overrides an
26350 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65  y behavior reque
26360 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a  sted by setting.
26370 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
26380 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
26390 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  or SQLITE_OPEN_S
263a0 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e  HAREDCACHE flag.
263b0 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
263c0 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70  psow</b>: ^The p
263d0 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e  sow parameter in
263e0 64 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20  dicates whether 
263f0 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20  or not the.**   
26400 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65    [powersafe ove
26410 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79  rwrite] property
26420 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f   does or does no
26430 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a  t apply to the.*
26440 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65  *     storage me
26450 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65  dia on which the
26460 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72   database file r
26470 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c  esides..**.**  <
26480 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62  li> <b>nolock</b
26490 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70  >: ^The nolock p
264a0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
264b0 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61  olean query para
264c0 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69  meter.**     whi
264d0 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c  ch if set disabl
264e0 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20  es file locking 
264f0 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72  in rollback jour
26500 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73  nal modes.  This
26510 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75  .**     is usefu
26520 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20  l for accessing 
26530 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20  a database on a 
26540 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20  filesystem that 
26550 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  does not.**     
26560 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e  support locking.
26570 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61    Caution:  Data
26580 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20  base corruption 
26590 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
265a0 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f  two.**     or mo
265b0 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69  re processes wri
265c0 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  te to the same d
265d0 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20  atabase and any 
265e0 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20  one of those.** 
265f0 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73      processes us
26600 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a  es nolock=1..**.
26610 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75  **  <li> <b>immu
26620 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  table</b>: ^The 
26630 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65  immutable parame
26640 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
26650 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61   query.**     pa
26660 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64  rameter that ind
26670 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
26680 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
26690 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20   stored on.**   
266a0 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69    read-only medi
266b0 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61  a.  ^When immuta
266c0 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69  ble is set, SQLi
266d0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
266e0 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62  the.**     datab
266f0 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  ase file cannot 
26700 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e  be changed, even
26710 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69   by a process wi
26720 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20  th higher.**    
26730 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20   privilege, and 
26740 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  so the database 
26750 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f  is opened read-o
26760 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b  nly and all lock
26770 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63  ing.**     and c
26780 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20  hange detection 
26790 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61  is disabled.  Ca
267a0 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74  ution: Setting t
267b0 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20  he immutable.** 
267c0 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20      property on 
267d0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
267e0 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63  that does in fac
267f0 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73  t change can res
26800 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e  ult.**     in in
26810 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65  correct query re
26820 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51  sults and/or [SQ
26830 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72  LITE_CORRUPT] er
26840 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65  rors..**     See
26850 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49   also: [SQLITE_I
26860 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e  OCAP_IMMUTABLE].
26870 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f  .**       .** </
26880 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69  ul>.**.** ^Speci
26890 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
268a0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
268b0 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
268c0 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f  t of a URI is no
268d0 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20  t an.** error.  
268e0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
268f0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
26900 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74  understand addit
26910 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70  ional query.** p
26920 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20  arameters.  See 
26930 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  "[query paramete
26940 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20  rs with special 
26950 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74  meaning to SQLit
26960 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  e]" for.** addit
26970 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
26980 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  n..**.** [[URI f
26990 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
269a0 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e  ]] <h3>URI filen
269b0 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33  ame examples</h3
269c0 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  >.**.** <table b
269d0 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d  order="1" align=
269e0 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69  center cellpaddi
269f0 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ng=5>.** <tr><th
26a00 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  > URI filenames 
26a10 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20  <th> Results.** 
26a20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
26a30 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
26a40 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
26a50 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
26a60 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
26a70 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72  irectory..** <tr
26a80 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
26a90 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72  /fred/data.db<br
26aa0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  >.**          fi
26ab0 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f  le:///home/fred/
26ac0 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a  data.db <br> .**
26ad0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
26ae0 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f  /localhost/home/
26af0 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
26b00 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  > <td> .**      
26b10 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74      Open the dat
26b20 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d  abase file "/hom
26b30 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
26b40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
26b50 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d  e://darkstar/hom
26b60 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
26b70 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
26b80 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b   An error. "dark
26b90 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72  star" is not a r
26ba0 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72  ecognized author
26bb0 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20  ity..** <tr><td 
26bc0 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61  style="white-spa
26bd0 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20  ce:nowrap"> .** 
26be0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
26bf0 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30  /C:/Documents%20
26c00 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66  and%20Settings/f
26c10 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61  red/Desktop/data
26c20 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20  .db.**     <td> 
26c30 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70  Windows only: Op
26c40 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
26c50 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20  a.db" on fred's 
26c60 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65  desktop on drive
26c70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e  .**          C:.
26c80 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25   Note that the %
26c90 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74  20 escaping in t
26ca0 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e  his example is n
26cb0 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20  ot strictly .** 
26cc0 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61           necessa
26cd0 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61  ry - space chara
26ce0 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65  cters can be use
26cf0 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20  d literally.**  
26d00 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66          in URI f
26d10 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72  ilenames..** <tr
26d20 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
26d30 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65  db?mode=ro&cache
26d40 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a  =private <td> .*
26d50 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
26d60 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
26d70 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
26d80 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64  rectory for read
26d90 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a  -only access..**
26da0 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64            Regard
26db0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
26dc0 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61  or not shared-ca
26dd0 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  che mode is enab
26de0 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  led by.**       
26df0 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20     default, use 
26e00 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e  a private cache.
26e10 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
26e20 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
26e30 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f  a.db?vfs=unix-do
26e40 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20  tfile <td>.**   
26e50 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
26e60 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
26e70 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73  a.db". Use the s
26e80 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78  pecial VFS "unix
26e90 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20  -dotfile".**    
26ea0 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20        that uses 
26eb0 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61  dot-files in pla
26ec0 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69  ce of posix advi
26ed0 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a  sory locking..**
26ee0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
26ef0 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64  ata.db?mode=read
26f00 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  only <td> .**   
26f10 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
26f20 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e   "readonly" is n
26f30 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f  ot a valid optio
26f40 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22  n for the "mode"
26f50 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c   parameter..** <
26f60 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55  /table>.**.** ^U
26f70 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  RI hexadecimal e
26f80 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
26f90 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72  (%HH) are suppor
26fa0 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70  ted within the p
26fb0 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79  ath and.** query
26fc0 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
26fd0 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69   URI. A hexadeci
26fe0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
26ff0 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  nce consists of 
27000 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67  a.** percent sig
27010 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77  n - "%" - follow
27020 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77  ed by exactly tw
27030 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69  o hexadecimal di
27040 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79  gits .** specify
27050 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c  ing an octet val
27060 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20  ue. ^Before the 
27070 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f  path or query co
27080 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a  mponents of a.**
27090 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72   URI filename ar
270a0 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74  e interpreted, t
270b0 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20  hey are encoded 
270c0 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20  using UTF-8 and 
270d0 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69  all .** hexadeci
270e0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
270f0 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79  nces replaced by
27100 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63   a single byte c
27110 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
27120 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f   corresponding o
27130 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72  ctet. If this pr
27140 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20  ocess generates 
27150 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38  an invalid UTF-8
27160 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68   encoding,.** th
27170 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
27180 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
27190 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
271a0 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
271b0 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
271c0 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
271d0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
271e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
271f0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
27200 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
27210 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
27220 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
27230 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
27240 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
27250 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
27260 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
27270 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
27280 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
27290 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
272a0 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
272b0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
272c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
272d0 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  )..**.** <b>Note
272e0 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74   to Windows Runt
272f0 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ime users:</b>  
27300 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69  The temporary di
27310 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20  rectory must be 
27320 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  set.** prior to 
27330 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
27340 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
27350 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74  3_open_v2().  Ot
27360 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73  herwise, various
27370 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61  .** features tha
27380 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73  t require the us
27390 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66  e of temporary f
273a0 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a  iles may fail..*
273b0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
273c0 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
273d0 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73  ectory].*/.int s
273e0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63  qlite3_open(.  c
273f0 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
27400 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
27410 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
27420 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
27430 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
27440 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
27450 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
27460 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
27470 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
27480 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
27490 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
274a0 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
274b0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
274c0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
274d0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
274e0 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
274f0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63  te3_open_v2(.  c
27500 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
27510 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
27520 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
27530 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
27540 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20   **ppDb,        
27550 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
27560 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69  db handle */.  i
27570 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20  nt flags,       
27580 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20         /* Flags 
27590 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
275a0 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20  *zVfs        /* 
275b0 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75  Name of VFS modu
275c0 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a  le to use */.);.
275d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
275e0 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46   Obtain Values F
275f0 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72  or URI Parameter
27600 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  s.**.** These ar
27610 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e  e utility routin
27620 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46  es, useful to VF
27630 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
27640 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a  s, that check.**
27650 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74   to see if a dat
27660 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61  abase file was a
27670 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69   URI that contai
27680 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71  ned a specific q
27690 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74  uery .** paramet
276a0 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62  er, and if so ob
276b0 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20  tains the value 
276c0 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61  of that query pa
276d0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
276e0 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62  f F is the datab
276f0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69  ase filename poi
27700 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f  nter passed into
27710 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74   the xOpen() met
27720 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53  hod of .** a VFS
27730 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
27740 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70  when the flags p
27750 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
27760 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a  n() has one or .
27770 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b  ** more of the [
27780 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
27790 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e   or [SQLITE_OPEN
277a0 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73  _MAIN_DB] bits s
277b0 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74  et and.** P is t
277c0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71  he name of the q
277d0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20  uery parameter, 
277e0 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
277f0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
27800 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  P) returns the v
27810 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a  alue of the P.**
27820 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74   parameter if it
27830 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c   exists or a NUL
27840 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64  L pointer if P d
27850 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61  oes not appear a
27860 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61  s a .** query pa
27870 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49  rameter on F.  I
27880 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70  f P is a query p
27890 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a  arameter of F.**
278a0 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74   has no explicit
278b0 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c   value, then sql
278c0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
278d0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a  er(F,P) returns.
278e0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
278f0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
27900 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
27910 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
27920 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73  ,P,B) routine as
27930 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20  sumes that P is 
27940 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72  a boolean.** par
27950 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
27960 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66  ns true (1) or f
27970 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69  alse (0) accordi
27980 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a  ng to the value.
27990 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71  ** of P.  The sq
279a0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
279b0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
279c0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
279d0 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ) if the.** valu
279e0 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d  e of query param
279f0 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
27a00 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20   "yes", "true", 
27a10 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a  or "on" in any.*
27a20 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65  * case or if the
27a30 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
27a40 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75  th a non-zero nu
27a50 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73  mber.  The .** s
27a60 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
27a70 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
27a80 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  es returns false
27a90 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75   (0) if the valu
27aa0 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61  e of.** query pa
27ab0 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
27ac0 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65   of "no", "false
27ad0 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61  ", or "off" in a
27ae0 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66  ny case or.** if
27af0 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
27b00 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63  s with a numeric
27b10 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20   zero.  If P is 
27b20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70  not a query.** p
27b30 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72  arameter on F or
27b40 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
27b50 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d   P is does not m
27b60 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a  atch any of the.
27b70 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73  ** above, then s
27b80 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
27b90 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
27ba0 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20  s (B!=0)..**.** 
27bb0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
27bc0 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75  int64(F,P,D) rou
27bd0 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68  tine converts th
27be0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74  e value of P int
27bf0 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69  o a.** 64-bit si
27c00 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
27c10 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e   returns that in
27c20 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50  teger, or D if P
27c30 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69   does not.** exi
27c40 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75  st.  If the valu
27c50 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68  e of P is someth
27c60 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61  ing other than a
27c70 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a  n integer, then.
27c80 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  ** zero is retur
27c90 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46  ned..** .** If F
27ca0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
27cb0 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  er, then sqlite3
27cc0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
27cd0 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ,P) returns NULL
27ce0 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
27cf0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
27d00 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49  B) returns B.  I
27d10 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c  f F is not a NUL
27d20 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a  L pointer and.**
27d30 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
27d40 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  se file pathname
27d50 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51   pointer that SQ
27d60 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f  Lite passed into
27d70 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46   the xOpen.** VF
27d80 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  S method, then t
27d90 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
27da0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
27db0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
27dc0 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72  bably.** undesir
27dd0 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  able..*/.const c
27de0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69  har *sqlite3_uri
27df0 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74  _parameter(const
27e00 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
27e10 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
27e20 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74  aram);.int sqlit
27e30 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63  e3_uri_boolean(c
27e40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
27e50 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
27e60 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75  aram, int bDefau
27e70 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  lt);.sqlite3_int
27e80 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  64 sqlite3_uri_i
27e90 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a  nt64(const char*
27ea0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
27eb0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
27ec0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27ed0 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
27ee0 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54   Messages.** MET
27ef0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
27f00 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
27f10 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a  recent sqlite3_*
27f20 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69   API call associ
27f30 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64  ated with .** [d
27f40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27f50 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68  on] D failed, th
27f60 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  en the sqlite3_e
27f70 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66  rrcode(D) interf
27f80 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  ace.** returns t
27f90 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
27fa0 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  lt code] or [ext
27fb0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
27fc0 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41  e] for that.** A
27fd0 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74  PI call..** If t
27fe0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
27ff0 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63  PI call was succ
28000 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20  essful,.** then 
28010 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
28020 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72   from sqlite3_er
28030 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
28040 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ined..** ^The sq
28050 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
28060 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
28070 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
28080 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
28090 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
280a0 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
280b0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
280c0 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
280d0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
280e0 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
280f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
28100 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
28110 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
28120 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
28130 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
28140 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
28150 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
28160 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
28170 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
28180 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
28190 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
281a0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
281b0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
281c0 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
281d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
281e0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
281f0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
28200 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
28210 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
28220 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
28230 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
28240 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
28250 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
28260 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
28270 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
28280 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
28290 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
282a0 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63  rrstr() interfac
282b0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e  e returns the En
282c0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74  glish-language t
282d0 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63  ext.** that desc
282e0 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c  ribes the [resul
282f0 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d  t code], as UTF-
28300 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  8..** ^(Memory t
28310 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
28320 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
28330 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
28340 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73  nally.** and mus
28350 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62  t not be freed b
28360 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
28370 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  n)^..**.** When 
28380 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
28390 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
283a0 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69  is in use, it mi
283b0 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61  ght be the.** ca
283c0 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64  se that a second
283d0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e   error occurs on
283e0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
283f0 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ad in between.**
28400 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65   the time of the
28410 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64   first error and
28420 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
28430 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  se interfaces..*
28440 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70  * When that happ
28450 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20  ens, the second 
28460 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
28470 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65  ported since the
28480 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
28490 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74   always report t
284a0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72  he most recent r
284b0 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64  esult.  To avoid
284c0 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74  .** this, each t
284d0 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e  hread can obtain
284e0 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f   exclusive use o
284f0 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
28500 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
28510 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71   by invoking [sq
28520 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
28530 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  r]([sqlite3_db_m
28540 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65  utex](D)) before
28550 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f   beginning.** to
28560 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b   use D and invok
28570 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
28580 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74  ex_leave]([sqlit
28590 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
285a0 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61   after.** all ca
285b0 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72  lls to the inter
285c0 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72  faces listed her
285d0 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e  e are completed.
285e0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
285f0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
28600 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
28610 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
28620 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
28630 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
28640 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
28650 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
28660 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
28670 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
28680 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
28690 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a   not be set..*/.
286a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
286b0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
286c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  ;.int sqlite3_ex
286d0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
286e0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e  qlite3 *db);.con
286f0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
28700 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
28710 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
28720 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
28730 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
28740 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
28750 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  rrstr(int);../*.
28760 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65  ** CAPI3REF: Pre
28770 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
28780 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
28790 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
287a0 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
287b0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
287c0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
287d0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
287e0 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
287f0 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
28800 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65  t that.** has be
28810 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  en compiled into
28820 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64   binary form and
28830 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20   is ready to be 
28840 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  evaluated..**.**
28850 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53   Think of each S
28860 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
28870 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75  a separate compu
28880 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68  ter program.  Th
28890 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
288a0 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65  L text is source
288b0 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72   code.  A prepar
288c0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
288d0 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63  ect .** is the c
288e0 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63  ompiled object c
288f0 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75  ode.  All SQL mu
28900 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
28910 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72  into a.** prepar
28920 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66  ed statement bef
28930 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75  ore it can be ru
28940 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  n..**.** The lif
28950 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65  e-cycle of a pre
28960 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
28970 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67  object usually g
28980 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  oes like this:.*
28990 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
289a0 3e 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65  > Create the pre
289b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
289c0 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
289d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
289e0 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ()]..** <li> Bin
289f0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72  d values to [par
28a00 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
28a10 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
28a20 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
28a30 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
28a40 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
28a50 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
28a60 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
28a70 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
28a80 69 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65  i> Reset the pre
28a90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
28aa0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
28ab0 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
28ac0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
28ad0 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
28ae0 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
28af0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
28b00 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
28b10 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
28b20 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
28b30 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  /ol>.*/.typedef 
28b40 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
28b50 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
28b60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28b70 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
28b80 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ts.** METHOD: sq
28b90 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lite3.**.** ^(Th
28ba0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
28bb0 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
28bc0 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
28bd0 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
28be0 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
28bf0 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
28c00 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
28c10 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
28c20 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
28c30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
28c40 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
28c50 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
28c60 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
28c70 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
28c80 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
28c90 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
28ca0 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
28cb0 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
28cc0 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
28cd0 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
28ce0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
28cf0 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
28d00 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
28d10 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
28d20 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
28d30 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
28d40 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
28d50 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
28d60 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
28d70 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
28d80 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
28d90 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
28da0 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
28db0 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
28dc0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
28dd0 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
28de0 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
28df0 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
28e00 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
28e10 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
28e20 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
28e30 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
28e40 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
28e50 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
28e60 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
28e70 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
28e80 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
28e90 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
28ea0 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
28eb0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
28ec0 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
28ed0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
28ee0 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
28ef0 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
28f00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
28f10 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
28f20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
28f30 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
28f40 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
28f50 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
28f60 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
28f70 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
28f80 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
28f90 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
28fa0 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
28fb0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
28fc0 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
28fd0 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
28fe0 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
28ff0 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
29000 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
29010 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
29020 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
29030 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
29040 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
29050 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
29060 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
29070 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
29080 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
29090 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
290a0 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
290b0 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
290c0 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
290d0 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
290e0 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
290f0 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
29100 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
29110 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
29120 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
29130 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
29140 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
29150 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
29160 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
29170 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
29180 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
29190 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
291a0 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
291b0 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
291c0 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
291d0 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
291e0 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
291f0 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
29200 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
29210 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
29220 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
29230 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
29240 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
29250 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
29260 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
29270 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
29280 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
29290 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
292a0 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
292b0 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
292c0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
292d0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
292e0 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
292f0 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
29300 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
29310 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
29320 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
29330 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
29340 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
29350 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
29360 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
29370 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
29380 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
29390 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
293a0 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
293b0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
293c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
293d0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
293e0 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
293f0 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
29400 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
29410 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
29420 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
29430 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
29440 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
29450 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
29460 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
29470 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
29480 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
29490 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
294a0 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
294b0 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
294c0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
294d0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
294e0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
294f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
29500 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
29510 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
29520 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
29530 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
29540 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
29550 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29560 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
29570 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
29580 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
29590 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
295a0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
295b0 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
295c0 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
295d0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
295e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
295f0 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
29600 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
29610 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29620 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
29630 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
29640 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
29650 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
29660 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
29670 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
29680 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
29690 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
296a0 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
296b0 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
296c0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
296d0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
296e0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
296f0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
29700 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
29710 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
29720 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
29730 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
29740 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
29750 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
29760 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29770 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
29780 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
29790 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
297a0 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
297b0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
297c0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
297d0 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
297e0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
297f0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
29800 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
29810 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
29820 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
29830 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29840 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
29850 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
29860 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
29870 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
29880 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
29890 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
298a0 74 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  t.  If [sqlite3_
298b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
298c0 0a 2a 2a 20 74 68 65 20 65 71 75 69 76 61 6c 65  .** the equivale
298d0 6e 74 20 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f  nt tries to allo
298e0 63 61 74 65 20 73 70 61 63 65 20 66 6f 72 20 6d  cate space for m
298f0 6f 72 65 20 74 68 61 6e 20 74 68 69 73 20 6d 61  ore than this ma
29900 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e  ny opcodes.** in
29910 20 61 20 73 69 6e 67 6c 65 20 70 72 65 70 61 72   a single prepar
29920 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e  ed statement, an
29930 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72   SQLITE_NOMEM er
29940 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
29950 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
29960 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
29970 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
29980 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
29990 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
299a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
299b0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
299c0 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
299d0 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
299e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
299f0 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
29a00 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29a10 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
29a20 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29a30 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
29a40 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
29a50 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
29a60 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
29a70 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
29a80 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
29a90 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29aa0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
29ab0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
29ac0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
29ad0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
29ae0 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
29af0 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
29b00 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
29b10 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
29b20 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29b30 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
29b40 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
29b50 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
29b60 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
29b70 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29b80 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
29b90 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
29ba0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
29bb0 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
29bc0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
29bd0 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
29be0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
29bf0 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
29c00 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29c10 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
29c20 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
29c30 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  gers.</dd>)^.**.
29c40 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29c50 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
29c60 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
29c70 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
29c80 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EADS</dt>.** <dd
29c90 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
29ca0 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79  ber of auxiliary
29cb0 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20   worker threads 
29cc0 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  that a single.**
29cd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29ce0 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e  ment] may start.
29cf0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
29d00 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
29d10 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
29d20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29d30 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
29d40 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
29d50 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
29d60 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
29d70 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
29d80 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
29d90 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
29da0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
29db0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
29dc0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
29dd0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
29de0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
29df0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
29e00 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
29e10 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
29e20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
29e30 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
29e40 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
29e50 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
29e60 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29e70 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
29e80 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
29e90 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29ea0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
29eb0 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
29ec0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29ed0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
29ee0 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
29ef0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29f00 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
29f10 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
29f20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29f30 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
29f40 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a  DS           11.
29f50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29f60 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
29f70 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
29f80 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
29f90 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
29fa0 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
29fb0 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55  lite3.** CONSTRU
29fc0 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
29fd0 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  mt.**.** To exec
29fe0 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
29ff0 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
2a000 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
2a010 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
2a020 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
2a030 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
2a040 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
2a050 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
2a060 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
2a070 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2a080 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
2a090 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
2a0a0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
2a0b0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
2a0c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
2a0d0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2a0e0 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
2a0f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2a100 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
2a110 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
2a120 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
2a130 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
2a140 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
2a150 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
2a160 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
2a170 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
2a180 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
2a190 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2a1a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2a1b0 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
2a1c0 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
2a1d0 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
2a1e0 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
2a1f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2a200 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
2a210 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
2a220 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
2a230 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  t is negative, t
2a240 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
2a250 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
2a260 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
2a270 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
2a280 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e  s positive, then
2a290 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75   it is the.** nu
2a2a0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65  mber of bytes re
2a2b0 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
2a2c0 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f  If nByte is zero
2a2d0 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72  , then no prepar
2a2e0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
2a2f0 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a  is generated..**
2a300 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
2a310 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75  nows that the su
2a320 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
2a330 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
2a340 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69   then.** there i
2a350 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72  s a small perfor
2a360 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
2a370 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  to passing an nB
2a380 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
2a390 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  at.** is the num
2a3a0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2a3b0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
2a3c0 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
2a3d0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
2a3e0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  minator..**.** ^
2a3f0 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
2a400 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
2a410 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
2a420 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
2a430 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
2a440 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
2a450 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
2a460 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
2a470 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
2a480 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
2a490 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
2a4a0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
2a4b0 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
2a4c0 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
2a4d0 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
2a4e0 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
2a4f0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
2a500 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
2a510 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a520 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
2a530 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
2a540 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
2a550 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
2a560 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
2a570 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
2a580 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
2a590 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
2a5a0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
2a5b0 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
2a5c0 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
2a5d0 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
2a5e0 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
2a5f0 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
2a600 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
2a610 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
2a620 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
2a630 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
2a640 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
2a650 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2a660 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
2a670 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
2a680 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
2a690 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
2a6a0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
2a6b0 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
2a6c0 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
2a6d0 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
2a6e0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
2a6f0 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
2a700 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
2a710 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2a720 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
2a730 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
2a740 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2a750 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
2a760 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
2a770 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
2a780 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
2a790 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
2a7a0 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
2a7b0 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
2a7c0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
2a7d0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
2a7e0 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
2a7f0 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69  * ^In the "v2" i
2a800 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
2a810 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a820 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
2a830 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
2a840 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
2a850 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
2a860 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
2a870 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
2a880 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
2a890 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2a8a0 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
2a8b0 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
2a8c0 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
2a8d0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
2a8e0 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
2a8f0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
2a900 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
2a910 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
2a920 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
2a930 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
2a940 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
2a950 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
2a960 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
2a970 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
2a980 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
2a990 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
2a9a0 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73  gain. As many as
2a9b0 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48   [SQLITE_MAX_SCH
2a9c0 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65  EMA_RETRY].** re
2a9d0 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72  tries will occur
2a9e0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
2a9f0 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20  step() gives up 
2aa00 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65  and returns an e
2aa10 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  rror..** </li>.*
2aa20 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
2aa30 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
2aa40 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
2aa50 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
2aa60 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
2aa70 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
2aa80 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
2aa90 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
2aaa0 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
2aab0 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
2aac0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2aad0 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
2aae0 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
2aaf0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
2ab00 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
2ab10 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
2ab20 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
2ab30 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
2ab40 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
2ab50 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
2ab60 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
2ab70 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
2ab80 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
2ab90 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
2aba0 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
2abb0 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
2abc0 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
2abd0 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
2abe0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
2abf0 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
2ac00 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
2ac10 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
2ac20 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
2ac30 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
2ac40 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
2ac50 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
2ac60 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
2ac70 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
2ac80 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
2ac90 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
2aca0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
2acb0 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
2acc0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
2acd0 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
2ace0 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
2acf0 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
2ad00 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
2ad10 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
2ad20 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
2ad30 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
2ad40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2ad50 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
2ad60 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
2ad70 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
2ad80 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
2ad90 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
2ada0 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
2adb0 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
2adc0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
2add0 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
2ade0 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
2adf0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
2ae00 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
2ae10 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
2ae20 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
2ae30 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
2ae40 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
2ae50 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
2ae60 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33  ITE_ENABLE_STAT3
2ae70 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2ae80 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
2ae90 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  ..** </li>.** </
2aea0 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ol>.*/.int sqlit
2aeb0 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
2aec0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2aed0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2aee0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2aef0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
2af00 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2af10 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
2af20 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2af30 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2af40 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2af50 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2af60 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2af70 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2af80 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2af90 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2afa0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
2afb0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2afc0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2afd0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2afe0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
2aff0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2b000 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2b010 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2b020 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2b030 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2b040 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2b050 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2b060 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
2b070 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2b080 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2b090 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2b0a0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2b0b0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2b0c0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2b0d0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2b0e0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2b0f0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
2b100 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2b110 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2b120 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2b130 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2b140 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
2b150 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2b160 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2b170 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2b180 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2b190 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2b1a0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2b1b0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2b1c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2b1d0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2b1e0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2b1f0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2b200 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2b210 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2b220 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2b230 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
2b240 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2b250 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2b260 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2b270 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2b280 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
2b290 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2b2a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2b2b0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2b2c0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
2b2d0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2b2e0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2b2f0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
2b300 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2b310 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2b320 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2b330 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2b340 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2b350 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2b360 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2b370 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2b380 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
2b390 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2b3a0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2b3b0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
2b3c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b3d0 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
2b3e0 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48  ment SQL.** METH
2b3f0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2b400 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2b410 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72  te3_sql(P) inter
2b420 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2b430 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79  ointer to a copy
2b440 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a   of the UTF-8.**
2b450 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
2b460 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70 61 72  o create [prepar
2b470 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20  ed statement] P 
2b480 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61  if P was.** crea
2b490 74 65 64 20 62 79 20 65 69 74 68 65 72 20 5b 73  ted by either [s
2b4a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2b4b0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
2b4c0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2b4d0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2b4e0 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50  3_expanded_sql(P
2b4f0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2b500 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2b510 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69   a UTF-8.** stri
2b520 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
2b530 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72  e SQL text of pr
2b540 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b550 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e   P with.** [boun
2b560 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78  d parameters] ex
2b570 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  panded..**.** ^(
2b580 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
2b590 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2b5a0 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65 64 20  ment is created 
2b5b0 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a  using the SQL.**
2b5c0 20 74 65 78 74 20 22 53 45 4c 45 43 54 20 24 61   text "SELECT $a
2b5d0 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 20  bc,:xyz" and if 
2b5e0 70 61 72 61 6d 65 74 65 72 20 24 61 62 63 20 69  parameter $abc i
2b5f0 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67  s bound to integ
2b600 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70  er 2345.** and p
2b610 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 73  arameter :xyz is
2b620 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73   unbound, then s
2b630 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69 6c  qlite3_sql() wil
2b640 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  l return.** the 
2b650 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c  original string,
2b660 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78   "SELECT $abc,:x
2b670 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33 5f  yz" but sqlite3_
2b680 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a  expanded_sql().*
2b690 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 53  * will return "S
2b6a0 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22  ELECT 2345,NULL"
2b6b0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
2b6c0 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2b6d0 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  sql() interface 
2b6e0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
2b6f0 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
2b700 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61  ory.** is availa
2b710 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ble to hold the 
2b720 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 68  result, or if th
2b730 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 65  e result would e
2b740 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 65  xceed the.** the
2b750 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 20   maximum string 
2b760 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e 65  length determine
2b770 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  d by the [SQLITE
2b780 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a  _LIMIT_LENGTH]..
2b790 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
2b7a0 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49  TE_TRACE_SIZE_LI
2b7b0 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  MIT] compile-tim
2b7c0 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20  e option limits 
2b7d0 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62  the size of.** b
2b7e0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 65  ound parameter e
2b7f0 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65  xpansions.  ^The
2b800 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52   [SQLITE_OMIT_TR
2b810 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
2b820 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73  e.** option caus
2b830 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  es sqlite3_expan
2b840 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77  ded_sql() to alw
2b850 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e  ays return NULL.
2b860 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69  .**.** ^The stri
2b870 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ng returned by s
2b880 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 73  qlite3_sql(P) is
2b890 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69   managed by SQLi
2b8a0 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74  te and is.** aut
2b8b0 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64  omatically freed
2b8c0 20 77 68 65 6e 20 74 68 65 20 70 72 65 70 61 72   when the prepar
2b8d0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
2b8e0 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54  finalized..** ^T
2b8f0 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  he string return
2b900 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78  ed by sqlite3_ex
2b910 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f  panded_sql(P), o
2b920 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64  n the other hand
2b930 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64  ,.** is obtained
2b940 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2b950 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73  alloc()] and mus
2b960 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68 65  t be free by the
2b970 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
2b980 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  by passing it to
2b990 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2b9a0 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
2b9b0 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
2b9c0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2b9d0 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
2b9e0 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73  3_expanded_sql(s
2b9f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2ba00 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2ba10 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
2ba20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
2ba30 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
2ba40 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f  atabase.** METHO
2ba50 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2ba60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ba70 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2ba80 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
2ba90 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
2baa0 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
2bab0 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
2bac0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2bad0 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
2bae0 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
2baf0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2bb00 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2bb10 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
2bb20 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
2bb30 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2bb40 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
2bb50 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
2bb60 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
2bb70 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
2bb80 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
2bb90 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
2bba0 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
2bbb0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2bbc0 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
2bbd0 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
2bbe0 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
2bbf0 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
2bc00 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
2bc10 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
2bc20 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
2bc30 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
2bc40 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
2bc50 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
2bc60 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
2bc70 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
2bc80 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
2bc90 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
2bca0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
2bcb0 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
2bcc0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2bcd0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2bce0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2bcf0 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
2bd00 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
2bd10 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
2bd20 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
2bd30 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
2bd40 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
2bd50 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
2bd60 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
2bd70 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
2bd80 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
2bd90 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
2bda0 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
2bdb0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2bdc0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
2bdd0 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
2bde0 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
2bdf0 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
2be00 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
2be10 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
2be20 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
2be30 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
2be40 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
2be50 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
2be60 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
2be70 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
2be80 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
2be90 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
2bea0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
2beb0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
2bec0 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
2bed0 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
2bee0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
2bef0 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
2bf00 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
2bf10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
2bf20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
2bf30 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
2bf40 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2bf50 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2bf60 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54  s on disk..** ^T
2bf70 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2bf80 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72  readonly() inter
2bf90 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2bfa0 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69  e for [BEGIN] si
2bfb0 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d  nce.** [BEGIN] m
2bfc0 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65 72  erely sets inter
2bfd0 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20 74  nal flags, but t
2bfe0 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20  he [BEGIN|BEGIN 
2bff0 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a  IMMEDIATE] and.*
2c000 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 45  * [BEGIN|BEGIN E
2c010 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e  XCLUSIVE] comman
2c020 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65 20  ds do touch the 
2c030 64 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f 0a  database and so.
2c040 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
2c050 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75 72  readonly() retur
2c060 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68 6f  ns false for tho
2c070 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a  se commands..*/.
2c080 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
2c090 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
2c0a0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2c0b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c0c0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
2c0d0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2c0e0 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
2c0f0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2c100 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2c110 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2c120 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66  t_busy(S) interf
2c130 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
2c140 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74   (non-zero) if t
2c150 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2c160 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73  statement] S has
2c170 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74   been stepped at
2c180 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e   least once usin
2c190 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  g .** [sqlite3_s
2c1a0 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20  tep(S)] but has 
2c1b0 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63  neither run to c
2c1c0 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72  ompletion (retur
2c1d0 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  ned.** [SQLITE_D
2c1e0 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ONE] from [sqlit
2c1f0 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72  e3_step(S)]) nor
2c200 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75  .** been reset u
2c210 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
2c220 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73  set(S)].  ^The s
2c230 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2c240 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  (S).** interface
2c250 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69   returns false i
2c260 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f S is a NULL po
2c270 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20  inter.  If S is 
2c280 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70  not a .** NULL p
2c290 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f  ointer and is no
2c2a0 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  t a pointer to a
2c2b0 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64   valid [prepared
2c2c0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
2c2d0 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20  bject, then the 
2c2e0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
2c2f0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
2c300 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
2c310 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
2c320 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
2c330 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20   in combination 
2c340 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
2c350 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61  mt()].** to loca
2c360 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20  te all prepared 
2c370 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
2c380 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74  iated with a dat
2c390 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63  abase .** connec
2c3a0 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e  tion that are in
2c3b0 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72   need of being r
2c3c0 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20  eset.  This can 
2c3d0 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20  be used,.** for 
2c3e0 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67  example, in diag
2c3f0 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20  nostic routines 
2c400 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72  to search for pr
2c410 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65  epared .** state
2c420 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68  ments that are h
2c430 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63  olding a transac
2c440 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e  tion open..*/.in
2c450 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  t sqlite3_stmt_b
2c460 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  usy(sqlite3_stmt
2c470 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2c480 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
2c490 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
2c4a0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
2c4b0 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
2c4c0 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
2c4d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c4e0 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
2c4f0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
2c500 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c510 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
2c520 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
2c530 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
2c540 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
2c550 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
2c560 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
2c570 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
2c580 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56  s it stores.  ^V
2c590 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
2c5a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2c5b0 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
2c5c0 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
2c5d0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
2c5e0 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
2c5f0 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
2c600 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
2c610 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
2c620 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
2c630 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
2c640 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
2c650 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
2c660 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2c670 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
2c680 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
2c690 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
2c6a0 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
2c6b0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
2c6c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
2c6d0 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
2c6e0 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
2c6f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
2c700 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
2c710 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
2c720 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
2c730 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2c740 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a  e3_value.  The.*
2c750 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
2c760 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63  _dup()] interfac
2c770 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
2c780 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77   construct a new
2c790 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73   .** protected s
2c7a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f  qlite3_value fro
2c7b0 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  m an unprotected
2c7c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2c7d0 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
2c7e0 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
2c7f0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
2c800 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
2c810 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
2c820 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e   is held.  An in
2c830 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
2c840 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
2c850 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2c860 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
2c870 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
2c880 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
2c890 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2c8a0 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
2c8b0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2c8c0 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
2c8d0 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
2c8e0 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  ith [SQLITE_THRE
2c8f0 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69  ADSAFE=0] and wi
2c900 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  th [sqlite3_thre
2c910 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e  adsafe()] return
2c920 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20  ing 0).** or if 
2c930 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e  SQLite is run in
2c940 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20   one of reduced 
2c950 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20  mutex modes .** 
2c960 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
2c970 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20  INGLETHREAD] or 
2c980 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2c990 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74  ULTITHREAD].** t
2c9a0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hen there is no 
2c9b0 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
2c9c0 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
2c9d0 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
2c9e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2c9f0 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20  bjects and they 
2ca00 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65  can be used inte
2ca10 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f  rchangeably.  Ho
2ca20 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61  wever,.** for ma
2ca30 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61  ximum code porta
2ca40 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63  bility it is rec
2ca50 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
2ca60 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74  plications.** st
2ca70 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73  ill make the dis
2ca80 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
2ca90 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
2caa0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2cab0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2cac0 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
2cad0 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
2cae0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
2caf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2cb00 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
2cb10 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
2cb20 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
2cb30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2cb40 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
2cb50 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2cb60 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
2cb70 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ted..** ^The sql
2cb80 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2cb90 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2cba0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2cbb0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
2cbc0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
2cbd0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2cbe0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
2cbf0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2cc00 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
2cc10 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
2cc20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
2cc30 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  nd_value()]..** 
2cc40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2cc50 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
2cc60 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
2cc70 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
2cc80 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2cc90 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2cca0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
2ccb0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
2ccc0 63 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ct sqlite3_value
2ccd0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
2cce0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ccf0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f   SQL Function Co
2cd00 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ntext Object.**.
2cd10 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
2cd20 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
2cd30 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
2cd40 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
2cd50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
2cd60 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20  ext object.  ^A 
2cd70 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
2cd80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
2cd90 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
2cda0 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
2cdb0 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
2cdc0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2cdd0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
2cde0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2cdf0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2ce00 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2ce10 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
2ce20 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
2ce30 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
2ce40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2ce50 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
2ce60 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
2ce70 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2ce80 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
2ce90 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
2cea0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
2ceb0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
2cec0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
2ced0 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
2cee0 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
2cef0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
2cf00 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
2cf10 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
2cf20 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
2cf30 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
2cf40 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
2cf50 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
2cf60 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45  Statements.** KE
2cf70 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61  YWORDS: {host pa
2cf80 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70  rameter} {host p
2cf90 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74  arameters} {host
2cfa0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d   parameter name}
2cfb0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
2cfc0 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53  QL parameter} {S
2cfd0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  QL parameters} {
2cfe0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
2cff0 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  g}.** METHOD: sq
2d000 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2d010 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
2d020 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
2d030 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
2d040 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2d050 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
2d060 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
2d070 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
2d080 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
2d090 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
2d0a0 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
2d0b0 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
2d0c0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
2d0d0 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
2d0e0 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
2d0f0 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
2d100 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
2d110 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
2d120 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
2d130 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
2d140 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
2d150 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
2d160 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
2d170 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
2d180 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
2d190 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
2d1a0 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
2d1b0 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
2d1c0 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
2d1d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
2d1e0 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
2d1f0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
2d200 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2d210 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
2d220 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2d230 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2d240 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2d250 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
2d260 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
2d270 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
2d280 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
2d290 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
2d2a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d2b0 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
2d2c0 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
2d2d0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
2d2e0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
2d2f0 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
2d300 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
2d310 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
2d320 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
2d330 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
2d340 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
2d350 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
2d360 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
2d370 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
2d380 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
2d390 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
2d3a0 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
2d3b0 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
2d3c0 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
2d3d0 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
2d3e0 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
2d3f0 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
2d400 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
2d410 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
2d420 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2d430 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
2d440 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
2d450 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
2d460 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
2d470 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
2d480 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
2d490 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
2d4a0 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
2d4b0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
2d4c0 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
2d4d0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
2d4e0 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
2d4f0 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
2d500 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
2d510 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2d520 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
2d530 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
2d540 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
2d550 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
2d560 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2d570 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
2d580 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f  nd_text16().** o
2d590 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  r sqlite3_bind_b
2d5a0 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  lob() is a NULL 
2d5b0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
2d5c0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2d5d0 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20  r.** is ignored 
2d5e0 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75  and the end resu
2d5f0 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  lt is the same a
2d600 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  s sqlite3_bind_n
2d610 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ull()..**.** ^(I
2d620 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
2d630 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
2d640 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
2d650 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
2d660 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
2d670 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
2d680 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
2d690 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
2d6a0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2d6b0 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
2d6c0 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
2d6d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
2d6e0 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49  racters.)^.** ^I
2d6f0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2d700 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2d710 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
2d720 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2d730 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67  xt16().** is neg
2d740 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
2d750 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
2d760 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
2d770 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
2d780 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
2d790 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
2d7a0 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
2d7b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2d7c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2d7d0 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  ) is negative, t
2d7e0 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76  hen.** the behav
2d7f0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2d800 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65  ..** If a non-ne
2d810 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61  gative fourth pa
2d820 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69  rameter is provi
2d830 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ded to sqlite3_b
2d840 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72  ind_text().** or
2d850 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2d860 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65  xt16() or sqlite
2d870 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2d880 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72  then.** that par
2d890 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74  ameter must be t
2d8a0 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a  he byte offset.*
2d8b0 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  * where the NUL 
2d8c0 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
2d8d0 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20   occur assuming 
2d8e0 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20  the string were 
2d8f0 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65  NUL.** terminate
2d900 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
2d910 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20  haracters occur 
2d920 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20  at byte offsets 
2d930 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68  less than .** th
2d940 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66  e value of the f
2d950 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2d960 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
2d970 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20  ng string value 
2d980 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  will.** contain 
2d990 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20  embedded NULs.  
2d9a0 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78  The result of ex
2d9b0 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76  pressions involv
2d9c0 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77  ing strings.** w
2d9d0 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
2d9e0 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
2d9f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
2da00 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2da10 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67   BLOB and string
2da20 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61   binding interfa
2da30 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74  ces.** is a dest
2da40 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
2da50 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
2da60 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
2da70 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
2da80 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
2da90 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
2daa0 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
2dab0 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
2dac0 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
2dad0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
2dae0 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66  ll to bind API f
2daf0 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ails..** ^If the
2db00 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2db10 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
2db20 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
2db30 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
2db40 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
2db50 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
2db60 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
2db70 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
2db80 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
2db90 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
2dba0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
2dbb0 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
2dbc0 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
2dbd0 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
2dbe0 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
2dbf0 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
2dc00 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
2dc10 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
2dc20 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
2dc30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2dc40 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
2dc50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
2dc60 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
2dc70 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2dc80 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  4() must be one 
2dc90 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  of.** [SQLITE_UT
2dca0 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
2dcb0 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  16], [SQLITE_UTF
2dcc0 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16BE], or [SQLIT
2dcd0 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f  E_UTF16LE].** to
2dce0 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63   specify the enc
2dcf0 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78  oding of the tex
2dd00 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  t in the third p
2dd10 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a  arameter.  If.**
2dd20 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d   the sixth argum
2dd30 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
2dd40 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20  ind_text64() is 
2dd50 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
2dd60 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73  * allowed values
2dd70 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72   shown above, or
2dd80 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63   if the text enc
2dd90 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
2dda0 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65  nt.** from the e
2ddb0 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
2ddc0 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70  d by the sixth p
2ddd0 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
2dde0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69  he behavior.** i
2ddf0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2de00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2de10 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
2de20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
2de30 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
2de40 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
2de50 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
2de60 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
2de70 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
2de80 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
2de90 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
2dea0 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
2deb0 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
2dec0 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
2ded0 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
2dee0 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
2def0 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
2df00 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
2df10 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
2df20 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
2df30 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
2df40 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
2df50 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
2df60 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
2df70 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
2df80 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
2df90 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
2dfa0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
2dfb0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
2dfc0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2dfd0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
2dfe0 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
2dff0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2e000 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
2e010 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
2e020 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
2e030 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
2e040 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
2e050 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
2e060 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
2e070 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
2e080 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
2e090 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
2e0a0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
2e0b0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
2e0c0 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
2e0d0 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
2e0e0 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
2e0f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2e100 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
2e110 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
2e120 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2e130 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
2e140 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
2e150 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
2e160 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
2e170 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2e180 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
2e190 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
2e1a0 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
2e1b0 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
2e1c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2e1d0 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
2e1e0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2e1f0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
2e200 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
2e210 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
2e220 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
2e230 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20  [SQLITE_TOOBIG] 
2e240 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2e250 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66  d if the size of
2e260 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
2e270 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d  B.** exceeds lim
2e280 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b  its imposed by [
2e290 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
2e2a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2e2b0 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c  GTH]) or.** [SQL
2e2c0 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e  ITE_MAX_LENGTH].
2e2d0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e  .** ^[SQLITE_RAN
2e2e0 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
2e2f0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2e300 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
2e310 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51   of range.  ^[SQ
2e320 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
2e330 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
2e340 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  c() fails..**.**
2e350 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2e360 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2e370 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
2e380 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2e390 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
2e3a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
2e3b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2e3c0 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
2e3d0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2e3e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e3f0 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2e400 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
2e410 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2e420 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34  ite3_bind_blob64
2e430 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e440 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2e450 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
2e460 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2e470 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
2e480 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2e490 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
2e4a0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2e4b0 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
2e4c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2e4d0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2e4e0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
2e4f0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2e500 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2e510 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
2e520 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
2e530 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2e540 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e550 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
2e560 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
2e570 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e  e3_stmt*,int,con
2e580 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69  st char*,int,voi
2e590 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2e5a0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2e5b0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2e5c0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2e5d0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
2e5e0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2e5f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2e600 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt64(sqlite3_stm
2e610 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
2e620 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  har*, sqlite3_ui
2e630 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2e640 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2e650 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75  oid(*)(void*), u
2e660 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63  nsigned char enc
2e670 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69  oding);.int sqli
2e680 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
2e690 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e6a0 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
2e6b0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2e6c0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2e6d0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2e6e0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
2e6f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2e700 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69  _zeroblob64(sqli
2e710 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2e720 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
2e730 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e740 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
2e750 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45  Parameters.** ME
2e760 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2e770 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  mt.**.** ^This r
2e780 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
2e790 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
2e7a0 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
2e7b0 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
2e7c0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2e7d0 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
2e7e0 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
2e7f0 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
2e800 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
2e810 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
2e820 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
2e830 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
2e840 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
2e850 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
2e860 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2e870 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
2e880 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
2e890 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
2e8a0 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
2e8b0 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
2e8c0 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
2e8d0 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
2e8e0 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
2e8f0 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
2e900 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
2e910 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
2e920 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
2e930 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
2e940 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
2e950 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
2e960 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65  he ?NNN form are
2e970 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
2e980 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
2e990 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a  he list.)^.**.**
2e9a0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2e9b0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2e9c0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2e9d0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2e9e0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2e9f0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2ea00 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2ea10 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
2ea20 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2ea30 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2ea40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2ea50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ea60 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
2ea70 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54  Parameter.** MET
2ea80 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2ea90 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2eaa0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2eab0 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
2eac0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
2ead0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
2eae0 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
2eaf0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
2eb00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2eb10 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
2eb20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
2eb30 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
2eb40 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2eb50 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
2eb60 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
2eb70 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
2eb80 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2eb90 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2eba0 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
2ebb0 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
2ebc0 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
2ebd0 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
2ebe0 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
2ebf0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
2ec00 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
2ec10 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
2ec20 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
2ec30 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
2ec40 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
2ec50 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
2ec60 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
2ec70 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
2ec80 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
2ec90 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
2eca0 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
2ecb0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2ecc0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
2ecd0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
2ece0 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
2ecf0 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
2ed00 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
2ed10 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
2ed20 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
2ed30 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
2ed40 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2ed50 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
2ed60 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
2ed70 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
2ed80 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
2ed90 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
2eda0 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
2edb0 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
2edc0 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
2edd0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ede0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2edf0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2ee00 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2ee10 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2ee20 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2ee30 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2ee40 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2ee50 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2ee60 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2ee70 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2ee80 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2ee90 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
2eea0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
2eeb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
2eec0 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
2eed0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
2eee0 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Name.** METHOD: 
2eef0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2ef00 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
2ef10 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
2ef20 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
2ef30 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
2ef40 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
2ef50 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
2ef60 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
2ef70 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
2ef80 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2ef90 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2efa0 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
2efb0 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
2efc0 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
2efd0 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
2efe0 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
2eff0 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
2f000 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
2f010 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
2f020 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
2f030 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
2f040 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
2f050 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
2f060 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2f070 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2f080 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2f090 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2f0a0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2f0b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2f0c0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2f0d0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2f0e0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2f0f0 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ame()]..*/.int s
2f100 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2f110 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
2f120 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
2f130 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
2f140 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2f150 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
2f160 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
2f170 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45   Statement.** ME
2f180 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2f190 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  mt.**.** ^Contra
2f1a0 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
2f1b0 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
2f1c0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
2f1d0 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
2f1e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2f1f0 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
2f200 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
2f210 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2f220 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
2f230 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
2f240 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
2f250 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
2f260 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
2f270 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
2f280 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2f290 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2f2a0 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
2f2b0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
2f2c0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2f2d0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  mt.**.** ^Return
2f2e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2f2f0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
2f300 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
2f310 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
2f320 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f330 2e 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69  . ^If this routi
2f340 6e 65 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ne returns 0, th
2f350 61 74 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a  at means the .**
2f360 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f370 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f  ment] returns no
2f380 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
2f390 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
2f3a0 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75  .** ^However, ju
2f3b0 73 74 20 62 65 63 61 75 73 65 20 74 68 69 73 20  st because this 
2f3c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2f3d0 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65  a positive numbe
2f3e0 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65  r does not.** me
2f3f0 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d  an that one or m
2f400 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 61 74 61  ore rows of data
2f410 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65   will be returne
2f420 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 20 73 74  d.  ^A SELECT st
2f430 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20  atement.** will 
2f440 61 6c 77 61 79 73 20 68 61 76 65 20 61 20 70 6f  always have a po
2f450 73 69 74 69 76 65 20 73 71 6c 69 74 65 33 5f 63  sitive sqlite3_c
2f460 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75  olumn_count() bu
2f470 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  t depending on t
2f480 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  he.** WHERE clau
2f490 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61  se constraints a
2f4a0 6e 64 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e  nd the table con
2f4b0 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 72  tent, it might r
2f4c0 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a  eturn no rows..*
2f4d0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2f4e0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2f4f0 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
2f500 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2f510 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2f520 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2f530 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
2f540 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
2f550 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
2f560 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2f570 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2f580 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
2f590 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
2f5a0 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
2f5b0 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
2f5c0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
2f5d0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2f5e0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2f5f0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
2f600 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2f610 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2f620 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2f630 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
2f640 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
2f650 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
2f660 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2f670 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2f680 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
2f690 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
2f6a0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2f6b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2f6c0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
2f6d0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2f6e0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2f6f0 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
2f700 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2f710 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
2f720 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
2f730 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
2f740 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
2f750 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2f760 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
2f770 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
2f780 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2f790 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
2f7a0 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
2f7b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2f7c0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2f7d0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2f7e0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2f7f0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2f800 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2f810 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2f820 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2f830 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2f840 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
2f850 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f860 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
2f870 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2f880 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
2f890 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
2f8a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2f8b0 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
2f8c0 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
2f8d0 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
2f8e0 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
2f8f0 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
2f900 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
2f910 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
2f920 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
2f930 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2f940 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2f950 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
2f960 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2f970 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
2f980 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
2f990 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
2f9a0 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
2f9b0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
2f9c0 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
2f9d0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2f9e0 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
2f9f0 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
2fa00 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
2fa10 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
2fa20 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
2fa30 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2fa40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2fa50 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2fa60 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
2fa70 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2fa80 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
2fa90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2faa0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2fab0 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
2fac0 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
2fad0 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  sult.** METHOD: 
2fae0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2faf0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2fb00 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
2fb10 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
2fb20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
2fb30 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
2fb40 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
2fb50 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
2fb60 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
2fb70 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
2fb80 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2fb90 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
2fba0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2fbb0 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
2fbc0 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
2fbd0 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
2fbe0 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
2fbf0 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
2fc00 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
2fc10 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
2fc20 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
2fc30 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
2fc40 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2fc50 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
2fc60 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
2fc70 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2fc80 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
2fc90 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
2fca0 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
2fcb0 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
2fcc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2fcd0 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
2fce0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
2fcf0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2fd00 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2fd10 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2fd20 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2fd30 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2fd40 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2fd50 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2fd60 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2fd70 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
2fd80 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
2fd90 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
2fda0 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
2fdb0 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
2fdc0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
2fdd0 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
2fde0 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
2fdf0 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
2fe00 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
2fe10 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
2fe20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2fe30 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2fe40 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
2fe50 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
2fe60 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
2fe70 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
2fe80 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
2fe90 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
2fea0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
2feb0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
2fec0 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
2fed0 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
2fee0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
2fef0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
2ff00 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
2ff10 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
2ff20 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
2ff30 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
2ff40 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2ff50 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
2ff60 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
2ff70 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
2ff80 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
2ff90 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
2ffa0 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
2ffb0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
2ffc0 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
2ffd0 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
2ffe0 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
2fff0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
30000 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
30010 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
30020 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
30030 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
30040 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
30050 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
30060 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
30070 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
30080 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
30090 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
300a0 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
300b0 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
300c0 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
300d0 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
300e0 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
300f0 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
30100 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
30110 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
30120 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
30130 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
30140 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
30150 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
30160 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
30170 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
30180 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
30190 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
301a0 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
301b0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
301c0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
301d0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
301e0 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
301f0 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
30200 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
30210 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
30220 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
30230 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
30240 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
30250 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
30260 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
30270 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
30280 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
30290 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
302a0 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
302b0 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
302c0 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
302d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
302e0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
302f0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
30300 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
30310 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
30320 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
30330 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
30340 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
30350 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
30360 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
30370 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
30380 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
30390 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
303a0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
303b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
303c0 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
303d0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
303e0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
303f0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
30400 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
30410 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
30420 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
30430 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
30440 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
30450 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
30460 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
30470 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
30480 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
30490 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
304a0 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
304b0 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
304c0 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
304d0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
304e0 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
304f0 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
30500 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30510 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
30520 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
30530 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
30540 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
30550 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
30560 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
30570 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
30580 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
30590 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
305a0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
305b0 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
305c0 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
305d0 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
305e0 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
305f0 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
30600 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
30610 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
30620 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
30630 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
30640 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
30650 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
30660 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
30670 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
30680 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
30690 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
306a0 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
306b0 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
306c0 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
306d0 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
306e0 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
306f0 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
30700 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
30710 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
30720 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
30730 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
30740 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
30750 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
30760 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
30770 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
30780 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
30790 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
307a0 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
307b0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
307c0 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
307d0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
307e0 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
307f0 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
30800 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
30810 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
30820 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
30830 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
30840 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
30850 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
30860 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
30870 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
30880 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
30890 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
308a0 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
308b0 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
308c0 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
308d0 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
308e0 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
308f0 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
30900 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
30910 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
30920 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
30930 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
30940 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
30950 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
30960 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
30970 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
30980 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
30990 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
309a0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
309b0 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
309c0 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
309d0 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
309e0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
309f0 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
30a00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
30a10 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
30a20 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
30a30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30a40 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
30a50 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
30a60 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
30a70 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
30a80 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
30a90 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
30aa0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
30ab0 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
30ac0 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
30ad0 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
30ae0 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
30af0 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
30b00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
30b10 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
30b20 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
30b30 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
30b40 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
30b50 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
30b60 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
30b70 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
30b80 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
30b90 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
30ba0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
30bb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30bc0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
30bd0 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
30be0 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
30bf0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
30c00 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
30c10 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
30c20 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
30c30 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
30c40 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
30c50 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
30c60 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
30c70 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
30c80 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
30c90 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
30ca0 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
30cb0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
30cc0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
30cd0 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
30ce0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
30cf0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
30d00 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
30d10 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
30d20 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
30d30 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
30d40 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
30d50 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
30d60 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
30d70 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
30d80 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
30d90 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
30da0 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
30db0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
30dc0 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
30dd0 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
30de0 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
30df0 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
30e00 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
30e10 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
30e20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
30e30 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
30e40 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
30e50 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
30e60 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
30e70 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
30e80 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
30e90 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
30ea0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
30eb0 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
30ec0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a  ccurs within an.
30ed0 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
30ee0 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
30ef0 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
30f00 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
30f10 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
30f20 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
30f30 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
30f40 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
30f50 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
30f60 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
30f70 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
30f80 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
30f90 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
30fa0 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
30fb0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
30fc0 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
30fd0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
30fe0 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
30ff0 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
31000 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
31010 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
31020 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
31030 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
31040 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
31050 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
31060 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
31070 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
31080 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
31090 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
310a0 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
310b0 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
310c0 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
310d0 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
310e0 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
310f0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
31100 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
31110 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
31120 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
31130 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
31140 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
31150 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
31160 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
31170 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
31180 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
31190 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
311a0 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
311b0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
311c0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
311d0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
311e0 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
311f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
31200 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
31210 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
31220 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
31230 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
31240 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
31250 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
31260 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
31270 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
31280 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
31290 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
312a0 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
312b0 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
312c0 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
312d0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
312e0 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
312f0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
31300 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
31310 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
31320 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
31330 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
31340 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
31350 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
31360 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
31370 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
31380 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
31390 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
313a0 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
313b0 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
313c0 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
313d0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
313e0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
313f0 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
31400 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
31410 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
31420 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
31430 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
31440 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
31450 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
31460 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
31470 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
31480 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
31490 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
314a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
314b0 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
314c0 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
314d0 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
314e0 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
314f0 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
31500 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
31510 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
31520 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
31530 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
31540 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
31550 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
31560 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
31570 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
31580 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
31590 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
315a0 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
315b0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
315c0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
315d0 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
315e0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
315f0 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
31600 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
31610 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
31620 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
31630 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
31640 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
31650 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
31660 66 74 65 72 20 5b 76 65 72 73 69 6f 6e 20 33 2e  fter [version 3.
31670 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74 65 6f 66  6.23.1] ([dateof
31680 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73  :3.6.23.1],.** s
31690 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65  qlite3_step() be
316a0 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b  gan.** calling [
316b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
316c0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
316d0 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61  n this circumsta
316e0 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68  nce rather.** th
316f0 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  an returning [SQ
31700 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54  LITE_MISUSE].  T
31710 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69  his is not consi
31720 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62  dered a compatib
31730 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62  ility.** break b
31740 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69  ecause any appli
31750 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72  cation that ever
31760 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c   receives an SQL
31770 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72  ITE_MISUSE error
31780 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79  .** is broken by
31790 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
317a0 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
317b0 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c  UTORESET] compil
317c0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a  e-time option.**
317d0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
317e0 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61  restore the lega
317f0 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  cy behavior..**.
31800 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
31810 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
31820 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
31830 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
31840 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
31850 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
31860 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
31870 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
31880 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
31890 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
318a0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
318b0 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
318c0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
318d0 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
318e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
318f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
31900 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
31910 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
31920 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
31930 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
31940 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
31950 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
31960 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
31970 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
31980 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
31990 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
319a0 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
319b0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
319c0 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
319d0 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
319e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
319f0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
31a00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
31a10 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
31a20 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
31a30 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
31a40 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
31a50 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
31a60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
31a70 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
31a80 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
31a90 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
31aa0 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
31ab0 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
31ac0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
31ad0 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
31ae0 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
31af0 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
31b00 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nded..*/.int sql
31b10 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
31b20 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
31b30 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
31b40 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
31b50 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20  a result set.** 
31b60 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
31b70 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
31b80 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
31b90 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  nt(P) interface 
31ba0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
31bb0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
31bc0 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
31bd0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
31be0 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
31bf0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
31c00 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64  .** ^If prepared
31c10 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65   statement P doe
31c20 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c  s not have resul
31c30 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  ts ready to retu
31c40 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73  rn.** (via calls
31c50 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
31c60 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71  _column_int | sq
31c70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29  lite3_column_*()
31c80 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ] of.** interfac
31c90 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  es) then sqlite3
31ca0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
31cb0 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68  eturns 0..** ^Th
31cc0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
31cd0 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
31ce0 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69  also returns 0 i
31cf0 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f P is a NULL po
31d00 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73  inter..** ^The s
31d10 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
31d20 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74  t(P) routine ret
31d30 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72  urns 0 if the pr
31d40 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a  evious call to.*
31d50 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  * [sqlite3_step]
31d60 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51  (P) returned [SQ
31d70 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68  LITE_DONE].  ^Th
31d80 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
31d90 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20  ount(P).** will 
31da0 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20  return non-zero 
31db0 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  if previous call
31dc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
31dd0 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a  p](P) returned.*
31de0 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  * [SQLITE_ROW], 
31df0 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61  except in the ca
31e00 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d  se of the [PRAGM
31e10 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61  A incremental_va
31e20 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69  cuum].** where i
31e30 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
31e40 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68   zero since each
31e50 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75   step of that mu
31e60 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67  lti-step.** prag
31e70 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c  ma returns 0 col
31e80 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a  umns of data..**
31e90 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
31ea0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
31eb0 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
31ec0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
31ed0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
31ee0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
31ef0 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
31f00 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
31f10 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
31f20 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
31f30 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
31f40 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
31f50 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
31f60 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
31f70 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
31f80 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
31f90 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
31fa0 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
31fb0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
31fc0 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
31fd0 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
31fe0 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
31ff0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
32000 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
32010 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
32020 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
32030 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
32040 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
32050 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
32060 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
32070 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
32080 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
32090 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
320a0 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
320b0 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
320c0 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
320d0 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
320e0 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
320f0 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
32100 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
32110 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
32120 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
32130 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
32140 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
32150 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
32160 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
32170 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
32180 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
32190 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
321a0 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
321b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
321c0 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
321d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
321e0 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
321f0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
32200 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
32210 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
32220 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
32230 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
32240 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
32250 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
32260 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
32270 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
32280 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
32290 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
322a0 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
322b0 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
322c0 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
322d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
322e0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
322f0 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
32300 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
32310 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
32320 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
32330 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
32340 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
32350 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
32360 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
32370 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
32380 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
32390 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
323a0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
323b0 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
323c0 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
323d0 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
323e0 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
323f0 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
32400 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
32410 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
32420 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
32430 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
32440 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
32450 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
32460 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
32470 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
32480 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
32490 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
324a0 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
324b0 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
324c0 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
324d0 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
324e0 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
324f0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
32500 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
32510 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
32520 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
32530 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
32540 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
32550 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
32560 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
32570 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
32580 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
32590 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
325a0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
325b0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
325c0 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
325d0 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
325e0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
325f0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
32600 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
32610 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
32620 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
32630 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
32640 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
32650 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
32660 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
32670 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
32680 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
32690 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
326a0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
326b0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
326c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
326d0 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
326e0 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
326f0 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
32700 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
32710 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
32720 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
32730 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
32740 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
32750 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
32760 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
32770 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
32780 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
32790 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
327a0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
327b0 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
327c0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
327d0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
327e0 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
327f0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
32800 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
32810 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
32820 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
32830 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
32840 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
32850 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
32860 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
32870 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
32880 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
32890 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
328a0 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
328b0 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
328c0 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
328d0 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
328e0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
328f0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
32900 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
32910 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
32920 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
32930 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
32940 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
32950 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
32960 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
32970 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
32980 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
32990 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
329a0 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
329b0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
329c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
329d0 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
329e0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
329f0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
32a00 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
32a10 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
32a20 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
32a30 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
32a40 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
32a50 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
32a60 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
32a70 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
32a80 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
32a90 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
32aa0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
32ab0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
32ac0 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
32ad0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
32ae0 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
32af0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
32b00 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
32b10 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
32b20 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
32b30 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
32b40 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
32b50 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
32b60 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
32b70 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
32b80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
32b90 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
32ba0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
32bb0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
32bc0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
32bd0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
32be0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
32bf0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
32c00 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
32c10 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
32c20 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
32c30 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
32c40 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
32c50 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
32c60 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
32c70 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
32c80 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
32c90 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
32ca0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
32cb0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
32cc0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
32cd0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
32ce0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
32cf0 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
32d00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
32d10 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
32d20 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
32d30 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
32d40 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
32d50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
32d60 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
32d70 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
32d80 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
32d90 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
32da0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
32db0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
32dc0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
32dd0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
32de0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
32df0 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
32e00 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
32e10 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
32e20 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
32e30 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
32e40 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
32e50 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
32e60 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
32e70 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
32e80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32e90 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
32ea0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32eb0 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
32ec0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
32ed0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
32ee0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
32ef0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
32f00 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
32f10 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
32f20 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
32f30 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
32f40 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
32f50 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
32f60 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
32f70 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
32f80 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
32f90 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
32fa0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
32fb0 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
32fc0 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
32fd0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
32fe0 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e   <b>Warning:</b>
32ff0 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
33000 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
33010 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
33020 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
33030 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
33040 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
33050 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64  In a multithread
33060 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a  ed environment,.
33070 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  ** an unprotecte
33080 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
33090 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20  object may only 
330a0 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77  be used safely w
330b0 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
330c0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
330d0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
330e0 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
330f0 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
33100 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
33110 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
33120 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
33130 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
33140 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
33150 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
33160 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
33170 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
33180 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
33190 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
331a0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
331b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
331c0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
331d0 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74   behavior is not
331e0 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a   threadsafe..**.
331f0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
33200 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
33210 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
33220 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
33230 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  .  ^For.** examp
33240 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
33250 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
33260 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
33270 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
33280 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
33290 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
332a0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
332b0 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
332c0 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
332d0 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
332e0 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
332f0 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
33300 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
33310 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
33320 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
33330 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
33340 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
33350 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
33360 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
33370 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
33380 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
33390 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
333a0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
333b0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
333c0 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
333d0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
333e0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
333f0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
33400 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
33410 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
33420 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
33430 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
33440 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
33450 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
33460 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
33470 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
33480 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
33490 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
334a0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
334b0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
334c0 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
334d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
334e0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
334f0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
33500 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
33510 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
33520 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
33530 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
33540 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
33550 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
33560 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
33570 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
33580 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
33590 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
335a0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
335b0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
335c0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
335d0 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
335e0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
335f0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
33600 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a  [CAST] to BLOB.*
33610 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
33620 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
33630 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
33640 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
33650 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
33660 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
33670 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
33680 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  L.** <tr><td>  T
33690 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
336a0 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
336b0 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
336c0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
336d0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
336e0 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
336f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
33700 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
33710 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
33720 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
33730 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
33740 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
33750 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
33760 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
33770 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
33780 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
33790 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
337a0 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
337b0 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
337c0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
337d0 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
337e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
337f0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
33800 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
33810 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
33820 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
33830 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
33840 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
33850 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
33860 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
33870 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
33880 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
33890 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
338a0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
338b0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
338c0 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
338d0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
338e0 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
338f0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
33900 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
33910 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
33920 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
33930 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
33940 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
33950 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
33960 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
33970 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
33980 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
33990 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
339a0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
339b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
339c0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
339d0 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
339e0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
339f0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
33a00 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
33a10 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
33a20 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
33a30 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
33a40 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
33a50 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
33a60 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
33a70 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
33a80 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
33a90 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
33aa0 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
33ab0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
33ac0 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
33ad0 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
33ae0 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
33af0 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
33b00 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
33b10 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
33b20 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
33b30 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
33b40 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
33b50 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
33b60 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
33b70 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
33b80 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
33b90 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
33ba0 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
33bb0 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
33bc0 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
33bd0 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
33be0 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
33bf0 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
33c00 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
33c10 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
33c20 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
33c30 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
33c40 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20  afest policy is 
33c50 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
33c60 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
33c70 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
33c80 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
33c90 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
33ca0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
33cb0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
33cc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
33cd0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
33ce0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
33cf0 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
33d00 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
33d10 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
33d20 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
33d30 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
33d40 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
33d50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33d60 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
33d70 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
33d80 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
33d90 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
33da0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
33db0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
33dc0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
33dd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33de0 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
33df0 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
33e00 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
33e10 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
33e20 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
33e30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
33e40 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
33e50 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
33e60 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
33e70 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
33e80 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
33e90 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
33ea0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
33eb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
33ec0 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
33ed0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
33ee0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
33ef0 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
33f00 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
33f10 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
33f20 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
33f30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33f40 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
33f50 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
33f60 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
33f70 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
33f80 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
33f90 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
33fa0 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
33fb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
33fc0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
33fd0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
33fe0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
33ff0 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
34000 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
34010 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
34020 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
34030 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
34040 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e  ically.  Do <em>
34050 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68  not</em> pass th
34060 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
34070 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
34080 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
34090 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
340a0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
340b0 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
340c0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
340d0 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
340e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
340f0 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
34100 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
34110 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
34120 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
34130 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
34140 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
34150 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
34160 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
34170 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
34180 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
34190 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
341a0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
341b0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
341c0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
341d0 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
341e0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
341f0 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20  EM].)^.*/.const 
34200 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
34210 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
34220 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
34230 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
34240 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
34250 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
34260 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
34270 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
34280 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
34290 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
342a0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
342b0 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
342c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
342d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
342e0 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
342f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
34300 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
34310 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
34320 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
34330 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
34340 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
34350 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
34360 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
34370 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
34380 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
34390 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
343a0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
343b0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
343c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
343d0 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
343e0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
343f0 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
34400 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
34410 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
34420 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
34430 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34440 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
34450 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
34460 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54  ject.** DESTRUCT
34470 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OR: sqlite3_stmt
34480 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34490 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
344a0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
344b0 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
344c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
344d0 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
344e0 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
344f0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
34500 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
34510 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  ed no errors.** 
34520 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  or if the statem
34530 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65  ent is never bee
34540 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65  n evaluated, the
34550 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  n sqlite3_finali
34560 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ze() returns.** 
34570 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20  SQLITE_OK.  ^If 
34580 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
34590 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74  evaluation of st
345a0 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64  atement S failed
345b0 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
345c0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65  3_finalize(S) re
345d0 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70  turns the approp
345e0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
345f0 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
34600 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
34610 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34620 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
34630 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
34640 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
34650 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20  t during.** the 
34660 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70  life cycle of [p
34670 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34680 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20  t] S:.** before 
34690 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65  statement S is e
346a0 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61  ver evaluated, a
346b0 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  fter.** one or m
346c0 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ore calls to [sq
346d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20  lite3_reset()], 
346e0 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c  or after any cal
346f0 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  l.** to [sqlite3
34700 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c  _step()] regardl
34710 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
34720 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d  r not the statem
34730 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c  ent has.** compl
34740 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a  eted execution..
34750 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20  **.** ^Invoking 
34760 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34770 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  () on a NULL poi
34780 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65  nter is a harmle
34790 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
347a0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
347b0 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76  must finalize ev
347c0 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74  ery [prepared st
347d0 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65  atement] in orde
347e0 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65  r to avoid.** re
347f0 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49  source leaks.  I
34800 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20  t is a grievous 
34810 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70  error for the ap
34820 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79  plication to try
34830 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65   to use.** a pre
34840 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
34850 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
34860 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e  n finalized.  An
34870 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61  y use of a prepa
34880 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
34890 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
348a0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e  en finalized can
348b0 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
348c0 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65  ined and.** unde
348d0 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
348e0 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c   such as segfaul
348f0 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72  ts and heap corr
34900 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  uption..*/.int s
34910 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
34920 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
34930 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
34940 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
34950 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
34960 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48  t Object.** METH
34970 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
34980 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
34990 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
349a0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
349b0 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
349c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
349d0 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20   object back to 
349e0 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
349f0 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
34a00 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e  e-executed..** ^
34a10 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
34a20 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
34a30 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
34a40 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
34a50 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
34a60 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
34a70 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
34a80 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
34a90 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
34aa0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
34ab0 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
34ac0 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
34ad0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
34ae0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
34af0 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
34b00 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
34b10 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63  tement] S.** bac
34b20 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
34b30 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
34b40 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  m..**.** ^If the
34b50 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
34b60 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
34b70 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
34b80 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
34b90 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
34ba0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
34bb0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
34bc0 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74  .** or if [sqlit
34bd0 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
34be0 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
34bf0 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
34c00 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * then [sqlite3_
34c10 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
34c20 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
34c30 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
34c40 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
34c50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
34c60 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
34c70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34c80 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
34c90 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
34ca0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34cb0 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
34cc0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
34cd0 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
34ce0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
34cf0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
34d00 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
34d10 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f   the values.** o
34d20 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
34d30 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
34d40 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
34d50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
34d60 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
34d70 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
34d80 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
34d90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
34da0 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
34db0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
34dc0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
34dd0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
34de0 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
34df0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
34e00 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
34e10 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
34e20 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
34e30 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
34e40 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54  unctions}.** MET
34e50 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
34e60 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
34e70 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
34e80 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63  y known as "func
34e90 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
34ea0 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20  utines").** are 
34eb0 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
34ec0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
34ed0 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65  regates or to re
34ee0 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
34ef0 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69  ior.** of existi
34f00 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
34f10 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
34f20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
34f30 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a  ences between.**
34f40 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
34f50 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63  are the text enc
34f60 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66  oding expected f
34f70 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  or.** the second
34f80 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
34f90 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63  name of the func
34fa0 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74  tion being creat
34fb0 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70  ed).** and the p
34fc0 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e  resence or absen
34fd0 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74  ce of a destruct
34fe0 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a  or callback for.
34ff0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
35000 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
35010 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
35020 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
35030 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
35040 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
35050 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
35060 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
35070 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
35080 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
35090 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
350a0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
350b0 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
350c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
350d0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
350e0 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
350f0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
35100 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
35110 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
35120 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
35130 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
35140 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
35150 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
35160 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
35170 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
35180 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
35190 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20  ed to 255 bytes 
351a0 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65  in a UTF-8.** re
351b0 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78  presentation, ex
351c0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
351d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
351e0 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
351f0 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c  name.** length l
35200 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38  imit is in UTF-8
35210 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72   bytes, not char
35220 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31  acters nor UTF-1
35230 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41  6 bytes.  .** ^A
35240 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
35250 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
35260 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
35270 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
35280 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  t in [SQLITE_MIS
35290 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72  USE] being retur
352a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
352b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
352c0 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65  (nArg).** is the
352d0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
352e0 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
352f0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
35300 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
35310 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d  . ^If this param
35320 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
35330 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
35340 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
35350 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
35360 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
35370 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
35380 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
35390 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
353a0 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
353b0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
353c0 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
353d0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
353e0 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
353f0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
35400 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
35410 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
35420 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
35430 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
35440 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
35450 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
35460 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
35470 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
35480 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
35490 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
354a0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68   parameters.  Th
354b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
354c0 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61  ould set this pa
354d0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53  rameter to.** [S
354e0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69  QLITE_UTF16LE] i
354f0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
35500 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
35510 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74  vokes .** [sqlit
35520 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
35530 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
35540 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
35550 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20  16BE] if the.** 
35560 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
35570 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f  nvokes [sqlite3_
35580 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
35590 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
355a0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  r.** [SQLITE_UTF
355b0 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  16] if [sqlite3_
355c0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
355d0 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c  is used, or [SQL
355e0 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68  ITE_UTF8].** oth
355f0 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61  erwise.  ^The sa
35600 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
35610 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
35620 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
35630 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72   using.** differ
35640 65 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65  ent preferred te
35650 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69  xt encodings, wi
35660 74 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70  th different imp
35670 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
35680 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e  .** each encodin
35690 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  g..** ^When mult
356a0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
356b0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
356c0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
356d0 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
356e0 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
356f0 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
35700 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
35710 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
35720 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ersion..**.** ^T
35730 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
35740 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c  ter may optional
35750 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20  ly be ORed with 
35760 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
35770 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67  ISTIC].** to sig
35780 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e  nal that the fun
35790 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79  ction will alway
357a0 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  s return the sam
357b0 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a  e result given.*
357c0 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  * the same input
357d0 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c  s within a singl
357e0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
357f0 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74    Most SQL funct
35800 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65  ions are.** dete
35810 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
35820 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d  built-in [random
35830 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ()] SQL function
35840 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   is an example o
35850 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  f a.** function 
35860 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65  that is not dete
35870 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
35880 53 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61  SQLite query pla
35890 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a  nner is able to.
358a0 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74  ** perform addit
358b0 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69  ional optimizati
358c0 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69  ons on determini
358d0 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20  stic functions, 
358e0 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65  so use.** of the
358f0 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49   [SQLITE_DETERMI
35900 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20  NISTIC] flag is 
35910 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72  recommended wher
35920 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a  e possible..**.*
35930 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
35940 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
35950 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
35960 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
35970 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
35980 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
35990 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
359a0 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
359b0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
359c0 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
359d0 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68  e sixth, seventh
359e0 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61   and eighth para
359f0 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
35a00 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
35a10 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
35a20 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
35a30 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
35a40 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
35a50 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
35a60 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61  ggregate. ^A sca
35a70 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
35a80 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
35a90 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
35aa0 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
35ab0 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20  back only; NULL 
35ac0 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65  pointers must be
35ad0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
35ae0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
35af0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
35b00 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
35b10 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
35b20 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
35b30 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
35b40 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
35b50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73  NULL pointer mus
35b60 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  t be passed for 
35b70 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74  xFunc. ^To delet
35b80 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a  e an existing.**
35b90 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
35ba0 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
35bb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66   NULL pointers f
35bc0 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
35bd0 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ction.** callbac
35be0 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ks..**.** ^(If t
35bf0 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  he ninth paramet
35c00 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
35c10 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
35c20 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a  () is not NULL,.
35c30 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65  ** then it is de
35c40 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
35c50 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
35c60 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54  a pointer. .** T
35c70 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
35c80 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
35c90 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  e function is de
35ca0 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79  leted, either by
35cb0 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f   being.** overlo
35cc0 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65  aded or when the
35cd0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
35ce0 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a  tion closes.)^.*
35cf0 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f  * ^The destructo
35d00 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65  r is also invoke
35d10 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  d if the call to
35d20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
35d30 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
35d40 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e   fails..** ^When
35d50 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
35d60 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
35d70 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  tenth parameter 
35d80 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a  is invoked, it.*
35d90 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69  * is passed a si
35da0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
35db0 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ich is a copy of
35dc0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
35dd0 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65   data .** pointe
35de0 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
35df0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
35e00 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
35e10 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e  e_function_v2().
35e20 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65  .**.** ^It is pe
35e30 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
35e40 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
35e50 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
35e60 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
35e70 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
35e80 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
35e90 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
35ea0 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
35eb0 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
35ec0 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
35ed0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
35ee0 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
35ef0 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
35f00 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d  mentation that m
35f10 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
35f20 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
35f30 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
35f40 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
35f50 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69  .  ^A function i
35f60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
35f70 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
35f80 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
35f90 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
35fa0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
35fb0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
35fc0 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
35fd0 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e  egative nArg.  ^
35fe0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
35ff0 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
36000 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
36010 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61  matches the data
36020 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
36030 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74   a better.** mat
36040 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
36050 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
36060 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
36070 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63  nt.  .** ^A func
36080 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
36090 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
360a0 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
360b0 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
360c0 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
360d0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
360e0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
360f0 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
36100 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
36110 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
36120 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d  6..**.** ^Built-
36130 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
36140 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
36150 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
36160 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
36170 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ons..**.** ^An a
36180 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36190 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
361a0 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
361b0 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
361c0 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
361d0 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c  wever, such call
361e0 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c  s must not.** cl
361f0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
36200 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20   connection nor 
36210 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65  finalize or rese
36220 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  t the prepared.*
36230 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77  * statement in w
36240 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f  hich the functio
36250 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
36260 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
36270 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
36280 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
36290 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
362a0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
362b0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
362c0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
362d0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
362e0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
362f0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
36300 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
36310 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
36320 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
36330 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
36340 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
36350 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
36360 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
36370 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
36380 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
36390 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f   *db,.  const vo
363a0 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  id *zFunctionNam
363b0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
363c0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
363d0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
363e0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
363f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
36400 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
36410 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
36420 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
36430 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
36440 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
36450 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
36460 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
36470 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
36480 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
36490 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
364a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
364b0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
364c0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
364d0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
364e0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
364f0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
36500 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
36510 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
36520 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
36530 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
36540 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
36550 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
36560 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
36570 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28  ntext*),.  void(
36580 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
36590 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
365a0 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
365b0 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ings.**.** These
365c0 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
365d0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
365e0 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
365f0 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
36600 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
36610 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
36620 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
36630 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
36640 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    1    /* IMP: R
36650 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a  -37514-35566 */.
36660 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
36670 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 20  TF16LE        2 
36680 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33     /* IMP: R-033
36690 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66  71-37637 */.#def
366a0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
366b0 42 45 20 20 20 20 20 20 20 20 33 20 20 20 20 2f  BE        3    /
366c0 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33  * IMP: R-51971-3
366d0 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20  4154 */.#define 
366e0 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
366f0 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
36700 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
36710 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
36720 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
36730 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70       5    /* Dep
36740 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69  recated */.#defi
36750 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
36760 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
36770 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36780 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
36790 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
367a0 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67  F: Function Flag
367b0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
367c0 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f  nstants may be O
367d0 52 65 64 20 74 6f 67 65 74 68 65 72 20 77 69 74  Red together wit
367e0 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
367f0 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72 72  E_UTF8 | preferr
36800 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
36810 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  ] as the fourth 
36820 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b  argument.** to [
36830 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
36840 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c  unction()], [sql
36850 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
36860 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
36870 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36880 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e  _function_v2()].
36890 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
368a0 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
368b0 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a      0x800../*.**
368c0 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65   CAPI3REF: Depre
368d0 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a  cated Functions.
368e0 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a  ** DEPRECATED.**
368f0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
36900 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61  ons are [depreca
36910 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20  ted].  In order 
36920 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
36930 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
36940 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
36950 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75  r code, these fu
36960 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  nctions continue
36970 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f   .** to be suppo
36980 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20  rted.  However, 
36990 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
369a0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a   should avoid.**
369b0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73   the use of thes
369c0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f  e functions.  To
369d0 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 72   encourage progr
369e0 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 0a  ammers to avoid.
369f0 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ** these functio
36a00 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20  ns, we will not 
36a10 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74 68 65  explain what the
36a20 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  y do..*/.#ifndef
36a30 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50   SQLITE_OMIT_DEP
36a40 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44  RECATED.SQLITE_D
36a50 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
36a60 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
36a70 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
36a80 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
36a90 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
36aa0 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
36ab0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
36ac0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
36ad0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
36ae0 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
36af0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
36b00 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
36b10 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
36b20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
36b30 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
36b40 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
36b50 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
36b60 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
36b70 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
36b80 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
36b90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
36ba0 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
36bb0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
36bc0 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  t),.            
36bd0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c            void*,
36be0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
36bf0 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
36c00 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
36c10 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20  g SQL Values.** 
36c20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
36c30 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  value.**.** The 
36c40 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
36c50 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
36c60 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
36c70 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
36c80 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
36c90 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
36ca0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
36cb0 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
36cc0 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
36cd0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
36ce0 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75    .**.** The xFu
36cf0 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
36d00 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
36d10 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
36d20 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
36d30 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
36d40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
36d50 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
36d60 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
36d70 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
36d80 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
36d90 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
36da0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
36db0 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33  egates..** The 3
36dc0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
36dd0 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
36de0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
36df0 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
36e00 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
36e10 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
36e20 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
36e30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
36e40 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
36e50 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
36e60 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
36e70 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
36e80 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
36e90 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
36ea0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
36eb0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
36ec0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
36ed0 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
36ee0 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
36ef0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
36f00 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
36f10 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
36f20 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
36f30 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
36f40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
36f50 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
36f60 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
36f70 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
36f80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
36f90 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
36fa0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
36fb0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
36fc0 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
36fd0 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72 6f  pt that these ro
36fe0 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
36ff0 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
37000 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
37010 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
37020 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
37030 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
37040 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
37050 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
37060 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
37070 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
37080 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
37090 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
370a0 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
370b0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
370c0 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
370d0 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
370e0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
370f0 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
37100 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37110 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
37120 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
37130 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
37140 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
37150 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
37160 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
37170 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
37180 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
37190 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
371a0 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
371b0 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
371c0 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
371d0 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
371e0 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
371f0 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
37200 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
37210 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
37220 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
37230 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
37240 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
37250 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
37260 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
37270 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
37280 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
37290 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
372a0 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
372b0 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
372c0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
372d0 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
372e0 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
372f0 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
37300 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
37310 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
37320 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
37330 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
37340 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
37350 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
37360 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
37370 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
37380 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
37390 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
373a0 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
373b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
373c0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
373d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
373e0 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
373f0 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
37400 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
37410 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
37420 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
37430 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
37440 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
37450 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
37460 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
37470 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
37480 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
37490 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
374a0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
374b0 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
374c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
374d0 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
374e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
374f0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
37500 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
37510 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
37520 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37530 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
37540 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
37550 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
37560 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
37570 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
37580 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
37590 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
375a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
375b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
375c0 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
375d0 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
375e0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
375f0 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
37600 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
37610 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
37620 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37630 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
37640 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
37650 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37660 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
37670 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
37680 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
37690 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
376a0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
376b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
376c0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
376d0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
376e0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
376f0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
37700 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
37710 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
37720 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
37730 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
37740 49 33 52 45 46 3a 20 46 69 6e 64 69 6e 67 20 54  I3REF: Finding T
37750 68 65 20 53 75 62 74 79 70 65 20 4f 66 20 53 51  he Subtype Of SQ
37760 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48  L Values.** METH
37770 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  OD: sqlite3_valu
37780 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
37790 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70  te3_value_subtyp
377a0 65 28 56 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  e(V) function re
377b0 74 75 72 6e 73 20 74 68 65 20 73 75 62 74 79 70  turns the subtyp
377c0 65 20 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70 70  e for.** an [app
377d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
377e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 61   SQL function] a
377f0 72 67 75 6d 65 6e 74 20 56 2e 20 20 54 68 65 20  rgument V.  The 
37800 73 75 62 74 79 70 65 0a 2a 2a 20 69 6e 66 6f 72  subtype.** infor
37810 6d 61 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  mation can be us
37820 65 64 20 74 6f 20 70 61 73 73 20 61 20 6c 69 6d  ed to pass a lim
37830 69 74 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 63  ited amount of c
37840 6f 6e 74 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f  ontext from.** o
37850 6e 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ne SQL function 
37860 74 6f 20 61 6e 6f 74 68 65 72 2e 20 20 55 73 65  to another.  Use
37870 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
37880 73 75 6c 74 5f 73 75 62 74 79 70 65 28 29 5d 0a  sult_subtype()].
37890 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 73 65  ** routine to se
378a0 74 20 74 68 65 20 73 75 62 74 79 70 65 20 66 6f  t the subtype fo
378b0 72 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  r the return val
378c0 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 66 75 6e  ue of an SQL fun
378d0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ction..**.** SQL
378e0 69 74 65 20 6d 61 6b 65 73 20 6e 6f 20 75 73 65  ite makes no use
378f0 20 6f 66 20 73 75 62 74 79 70 65 20 69 74 73 65   of subtype itse
37900 6c 66 2e 20 20 49 74 20 6d 65 72 65 6c 79 20 70  lf.  It merely p
37910 61 73 73 65 73 20 74 68 65 20 73 75 62 74 79 70  asses the subtyp
37920 65 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 72 65  e.** from the re
37930 73 75 6c 74 20 6f 66 20 6f 6e 65 20 5b 61 70 70  sult of one [app
37940 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
37950 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 69   SQL function] i
37960 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74  nto the.** input
37970 20 6f 66 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a   of another..*/.
37980 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 71 6c  unsigned int sql
37990 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79  ite3_value_subty
379a0 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
379b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
379c0 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 20 46 72  REF: Copy And Fr
379d0 65 65 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a  ee SQL Values.**
379e0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
379f0 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  _value.**.** ^Th
37a00 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
37a10 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65  dup(V) interface
37a20 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
37a30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
37a40 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 44  lue].** object D
37a50 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
37a60 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 63  ointer to that c
37a70 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  opy.  ^The [sqli
37a80 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 74 75 72  te3_value] retur
37a90 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70 72 6f  ned.** is a [pro
37aa0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
37ab0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65 76 65  alue] object eve
37ac0 6e 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 69  n if the input i
37ad0 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  s not..** ^The s
37ae0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
37af0 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (V) interface re
37b00 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 56 20  turns NULL if V 
37b10 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20 61 0a  is NULL or if a.
37b20 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
37b30 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  tion fails..**.*
37b40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
37b50 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 6e 74  alue_free(V) int
37b60 65 72 66 61 63 65 20 66 72 65 65 73 20 61 6e 20  erface frees an 
37b70 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
37b80 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76 69 6f  object.** previo
37b90 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
37ba0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
37bb0 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66 20 56  e_dup()].  ^If V
37bc0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
37bd0 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  er.** then sqlit
37be0 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29  e3_value_free(V)
37bf0 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
37c00 6f 2d 6f 70 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  o-op..*/.sqlite3
37c10 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
37c20 76 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 20  value_dup(const 
37c30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37c40 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 76 61  .void sqlite3_va
37c50 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33  lue_free(sqlite3
37c60 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
37c70 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
37c80 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
37c90 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20  tion Context.** 
37ca0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
37cb0 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  context.**.** Im
37cc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
37cd0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
37ce0 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
37cf0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  s.** routine to 
37d00 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
37d10 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
37d20 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  r state..**.** ^
37d30 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
37d40 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
37d50 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
37d60 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
37d70 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61  led .** for a pa
37d80 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
37d90 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c  te function, SQL
37da0 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73  ite.** allocates
37db0 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65   N of memory, ze
37dc0 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65  roes out that me
37dd0 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
37de0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
37df0 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79  o the new memory
37e00 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  . ^On second and
37e10 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
37e20 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
37e30 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
37e40 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
37e50 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
37e60 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a  ion instance,.**
37e70 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
37e80 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53   is returned.  S
37e90 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
37ea0 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f  _context() is no
37eb0 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  rmally.** called
37ec0 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69   once for each i
37ed0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
37ee0 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20   xStep callback 
37ef0 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20  and then one.** 
37f00 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74  last time when t
37f10 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
37f20 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
37f30 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d  ^(When no rows m
37f40 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65  atch.** an aggre
37f50 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
37f60 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b  xStep() callback
37f70 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
37f80 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d  e function.** im
37f90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
37fa0 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64  never called and
37fb0 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c   xFinal() is cal
37fc0 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  led exactly once
37fd0 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61  ..** In those ca
37fe0 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67  ses, sqlite3_agg
37ff0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
38000 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
38010 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73   for the.** firs
38020 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68  t time from with
38030 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a  in xFinal().)^.*
38040 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
38050 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
38060 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
38070 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
38080 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e  pointer .** when
38090 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66   first called if
380a0 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
380b0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
380c0 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a   or if a memory.
380d0 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f  ** allocate erro
380e0 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
380f0 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  ^(The amount of 
38100 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20  space allocated 
38110 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  by sqlite3_aggre
38120 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
38130 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ) is.** determin
38140 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61  ed by the N para
38150 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73  meter on first s
38160 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20  uccessful call. 
38170 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a   Changing the.**
38180 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73   value of N in s
38190 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
381a0 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
381b0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69  ate_context() wi
381c0 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  thin.** the same
381d0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
381e0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c  ion instance wil
381f0 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65  l not resize the
38200 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
38210 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e  ation.)^  Within
38220 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
38230 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74  back, it is cust
38240 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20  omary to set.** 
38250 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20  N=0 in calls to 
38260 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
38270 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73  e_context(C,N) s
38280 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f  o that no .** po
38290 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61  intless memory a
382a0 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72  llocations occur
382b0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
382c0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
382d0 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
382e0 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
382f0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
38300 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
38310 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
38320 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
38330 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
38340 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
38350 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
38360 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
38370 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
38380 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
38390 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
383a0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
383b0 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
383c0 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
383d0 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
383e0 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
383f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
38400 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
38410 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
38420 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
38430 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
38440 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
38450 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
38460 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
38470 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
38480 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
38490 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
384a0 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
384b0 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
384c0 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
384d0 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
384e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
384f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
38500 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
38510 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
38520 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
38530 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
38540 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
38550 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
38560 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
38570 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
38580 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
38590 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
385a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
385b0 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
385c0 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
385d0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
385e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
385f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
38600 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
38610 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
38620 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
38630 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
38640 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
38650 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
38660 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
38670 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
38680 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
38690 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
386a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
386b0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
386c0 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
386d0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
386e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a  ite3_context.**.
386f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
38700 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
38710 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
38720 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
38730 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
38740 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
38750 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65  connection] (the
38760 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a   1st parameter).
38770 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
38780 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
38790 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
387a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
387b0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
387c0 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
387d0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere