/ Hex Artifact Content
Login

Artifact b58190e2bc024865aef7d589b0edb1fd61b37962d126d9fcb581f456837b0c14:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65  LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 5b 76 65 72 73 69 6f  ** Since [versio
0f00: 6e 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65  n 3.6.18] ([date
0f10: 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a  of:3.6.18]), .**
0f20: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
0f30: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
0f40: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
0f50: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
0f60: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
0f70: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
0f80: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0f90: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
0fa0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
0fb0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
0fc0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
0fd0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
0fe0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
0ff0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
1000: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
1010: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
1020: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
1030: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
1040: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
1050: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
1060: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
1070: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
1080: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e  -in (UTC) and an
1090: 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66   SHA1.** hash of
10a0: 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72   the entire sour
10b0: 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53  ce tree..**.** S
10c0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
10d0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c  3_libversion()],
10e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  .** [sqlite3_lib
10f0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
1100: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72  ], [sqlite3_sour
1110: 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ceid()],.** [sql
1120: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
1130: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
1140: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  e_id()]..*/.#def
1150: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ine SQLITE_VERSI
1160: 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52  ON        "--VER
1170: 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c  S--".#define SQL
1180: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1190: 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d  ER --VERSION-NUM
11a0: 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65 20 53 51  BER--.#define SQ
11b0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20  LITE_SOURCE_ID  
11c0: 20 20 20 20 22 2d 2d 53 4f 55 52 43 45 2d 49 44      "--SOURCE-ID
11d0: 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  --"../*.** CAPI3
11e0: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
11f0: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75  brary Version Nu
1200: 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  mbers.** KEYWORD
1210: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  S: sqlite3_versi
1220: 6f 6e 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  on sqlite3_sourc
1230: 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  eid.**.** These 
1240: 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69  interfaces provi
1250: 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  de the same info
1260: 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b  rmation as the [
1270: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c  SQLITE_VERSION],
1280: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1290: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64  ION_NUMBER], and
12a0: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
12b0: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
12c0: 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74  or macros.** but
12d0: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20   are associated 
12e0: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79  with the library
12f0: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1300: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28  header file.  ^(
1310: 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67  Cautious.** prog
1320: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e  rammers might in
1330: 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73  clude assert() s
1340: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
1350: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
1360: 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74  o.** verify that
1370: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
1380: 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66   by these interf
1390: 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d  aces match the m
13a0: 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20  acros in.** the 
13b0: 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73  header, and thus
13c0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
13d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a   application is.
13e0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
13f0: 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72   matching librar
1400: 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c  y and header fil
1410: 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  es..**.** <block
1420: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61  quote><pre>.** a
1430: 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c  ssert( sqlite3_l
1440: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1450: 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49  ()==SQLITE_VERSI
1460: 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20  ON_NUMBER );.** 
1470: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73  assert( strcmp(s
1480: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1490: 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  ),SQLITE_SOURCE_
14a0: 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73  ID)==0 );.** ass
14b0: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69  ert( strcmp(sqli
14c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
14d0: 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29  ,SQLITE_VERSION)
14e0: 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ==0 );.** </pre>
14f0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1500: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1510: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1520: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e  ing constant con
1530: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f  tains the text o
1540: 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  f [SQLITE_VERSIO
1550: 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54  N].** macro.  ^T
1560: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
1570: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e  rsion() function
1580: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1590: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20  er to the.** to 
15a0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  the sqlite3_vers
15b0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
15c0: 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  stant.  The sqli
15d0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
15e0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
15f0: 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65  provided for use
1600: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44   in DLLs since D
1610: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79  LL users usually
1620: 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20   do not have.** 
1630: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f  direct access to
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1650: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c  s within the DLL
1660: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
1670: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1680: 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20  mber() function 
1690: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
16a0: 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b  er equal to.** [
16b0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
16c0: 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71  UMBER].  ^The sq
16d0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
16e0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
16f0: 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
1700: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73  to a string cons
1710: 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65  tant whose value
1720: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
1730: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
1740: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1750: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e  processor macro.
1760: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1770: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e   [sqlite_version
1780: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f  ()] and [sqlite_
1790: 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f  source_id()]..*/
17a0: 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
17b0: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65  onst char sqlite
17c0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e  3_version[];.con
17d0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
17e0: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64  _libversion(void
17f0: 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
1800: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1810: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
1820: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1830: 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  mber(void);../*.
1840: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1850: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f  -Time Library Co
1860: 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  mpilation Option
1870: 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a  s Diagnostics.**
1880: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1890: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
18a0: 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  sed() function r
18b0: 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a  eturns 0 or 1 .*
18c0: 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65  * indicating whe
18d0: 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69  ther the specifi
18e0: 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65  ed option was de
18f0: 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d  fined at .** com
1900: 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65  pile time.  ^The
1910: 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20   SQLITE_ prefix 
1920: 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66  may be omitted f
1930: 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69  rom the .** opti
1940: 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74  on name passed t
1950: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  o sqlite3_compil
1960: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20  eoption_used(). 
1970: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f  on_get() functio
19a0: 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69  n allows iterati
19b0: 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c  ng.** over the l
19c0: 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74  ist of options t
19d0: 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64  hat were defined
19e0: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
19f0: 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67   by.** returning
1a00: 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c   the N-th compil
1a10: 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74  e time option st
1a20: 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20  ring.  ^If N is 
1a30: 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a  out of range,.**
1a40: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1a50: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74  option_get() ret
1a60: 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1a70: 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ter.  ^The SQLIT
1a80: 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73  E_ .** prefix is
1a90: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e   omitted from an
1aa0: 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  y strings return
1ab0: 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
1ac0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1ad0: 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75  get()..**.** ^Su
1ae0: 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69  pport for the di
1af0: 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f  agnostic functio
1b00: 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ns sqlite3_compi
1b10: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a  leoption_used().
1b20: 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
1b30: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b40: 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  () may be omitte
1b50: 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20  d by specifying 
1b60: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
1b70: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
1b80: 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e  ON_DIAGS] option
1b90: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
1ba0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1bb0: 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  : SQL functions 
1bc0: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f  [sqlite_compileo
1bd0: 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e  ption_used()] an
1be0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  d.** [sqlite_com
1bf0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1c00: 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69  ] and the [compi
1c10: 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d  le_options pragm
1c20: 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  a]..*/.#ifndef S
1c30: 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49  QLITE_OMIT_COMPI
1c40: 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 69  LEOPTION_DIAGS.i
1c50: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nt sqlite3_compi
1c60: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f  leoption_used(co
1c70: 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61  nst char *zOptNa
1c80: 6d 65 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  me);.const char 
1c90: 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65  *sqlite3_compile
1ca0: 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e  option_get(int N
1cb0: 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
1cc0: 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
1cd0: 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69  To See If The Li
1ce0: 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73  brary Is Threads
1cf0: 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  afe.**.** ^The s
1d00: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1d10: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  e() function ret
1d20: 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64  urns zero if and
1d30: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69   only if.** SQLi
1d40: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  te was compiled 
1d50: 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f  with mutexing co
1d60: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1d70: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1d80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1d90: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1da0: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1db0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1dc0: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1dd0: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1de0: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1df0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1e00: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1e10: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1e20: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1e30: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1e40: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1e50: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1e60: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1e70: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1e80: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1e90: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1ea0: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1eb0: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1ec0: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1ed0: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1ee0: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1ef0: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1f00: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1f10: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1f20: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1f30: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1f40: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1f50: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1f60: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1f70: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1f80: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1f90: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1fa0: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1fb0: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1fc0: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1fd0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1fe0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1ff0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2010: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
2020: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
2030: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
2040: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
2050: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
2060: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
2070: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
2080: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
2090: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
20a0: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
20b0: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
20c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
20d0: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
20e0: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
20f0: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
2100: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
2110: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
2120: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
2130: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
2140: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
2150: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
2160: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
2170: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2180: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2190: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
21a0: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
21b0: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
21c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
21d0: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
21e0: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
21f0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2200: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2210: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
2220: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
2230: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
2240: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
2250: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
2260: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
2270: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2280: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2290: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
22a0: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
22b0: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
22c0: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
22d0: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
22e0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
22f0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2300: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2310: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
2320: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
2330: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
2340: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
2350: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
2360: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
2370: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2380: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2390: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
23a0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
23b0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23c0: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
23d0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23e0: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
23f0: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2400: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2410: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2420: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
2430: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
2440: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
2450: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
2460: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
2470: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2480: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2490: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
24a0: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
24b0: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
24c0: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
24d0: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
24e0: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
24f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2500: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2510: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
2520: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2530: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
2540: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
2550: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
2560: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
2570: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2580: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2590: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
25a0: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
25b0: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
25c0: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
25d0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
25e0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
25f0: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2600: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2610: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
2620: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
2630: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
2640: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
2650: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
2660: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2670: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2680: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2690: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
26a0: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
26b0: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
26c0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
26d0: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
26e0: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
26f0: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2700: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2710: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
2720: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
2730: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
2740: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
2750: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
2760: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2770: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2780: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2790: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
27a0: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
27b0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
27c0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
27d0: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
27e0: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
27f0: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2800: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2810: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2820: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
2830: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
2840: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
2850: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
2860: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
2870: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2880: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2890: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
28a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
28b0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
28c0: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
28d0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
28e0: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
28f0: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2900: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2910: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
2920: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2930: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
2940: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
2950: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 23 20  sqlite_int64;.# 
2960: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 55 49 4e  ifdef SQLITE_UIN
2970: 54 36 34 5f 54 59 50 45 0a 20 20 20 20 74 79 70  T64_TYPE.    typ
2980: 65 64 65 66 20 53 51 4c 49 54 45 5f 55 49 4e 54  edef SQLITE_UINT
2990: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75  64_TYPE sqlite_u
29a0: 69 6e 74 36 34 3b 0a 23 20 65 6c 73 65 20 20 0a  int64;.# else  .
29b0: 20 20 20 20 74 79 70 65 64 65 66 20 75 6e 73 69      typedef unsi
29c0: 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36  gned SQLITE_INT6
29d0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69  4_TYPE sqlite_ui
29e0: 6e 74 36 34 3b 0a 23 20 65 6e 64 69 66 0a 23 65  nt64;.# endif.#e
29f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2a00: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2a10: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2a20: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2a30: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2a40: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2a50: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2a60: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2a70: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2a80: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2a90: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2aa0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
2ab0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
2ac0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
2ad0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
2ae0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
2af0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2b00: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2b10: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2b20: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2b30: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2b40: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2b50: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2b60: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2b70: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2b80: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2b90: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
2ba0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
2bb0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
2bc0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
2bd0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2be0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
2bf0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2c00: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
2c10: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
2c20: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
2c30: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2c40: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65  ose_v2() routine
2c50: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72  s are destructor
2c60: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71  s.** for the [sq
2c70: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2c80: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2c90: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2ca0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2cb0: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  () return [SQLIT
2cc0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20  E_OK] if.** the 
2cd0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2ce0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79   is successfully
2cf0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
2d00: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
2d10: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64   resources are d
2d20: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a  eallocated..**.*
2d30: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2d40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2d50: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2d60: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2d70: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2d80: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65  nts or unfinishe
2d90: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
2da0: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71   objects then sq
2db0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
2dc0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
2dd0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2de0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74  ion open and ret
2df0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
2e00: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
2e10: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
2e20: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69  called with unfi
2e30: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2e40: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
2e50: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  nd/or unfinished
2e60: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73   sqlite3_backups
2e70: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
2e80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
2e90: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75  ecomes.** an unu
2ea0: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77  sable "zombie" w
2eb0: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61  hich will automa
2ec0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c  tically be deall
2ed0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a  ocated when the.
2ee0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  ** last prepared
2ef0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2f00: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c  nalized or the l
2f10: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ast sqlite3_back
2f20: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65  up is.** finishe
2f30: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
2f40: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72  close_v2() inter
2f50: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
2f60: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a   for use with.**
2f70: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20   host languages 
2f80: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65  that are garbage
2f90: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20   collected, and 
2fa0: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20  where the order 
2fb0: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74  in which.** dest
2fc0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c  ructors are call
2fd0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  ed is arbitrary.
2fe0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2ff0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
3000: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
3010: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
3020: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3030: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
3040: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
3050: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
3060: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20  ndles], and .** 
3070: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
3080: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d  finish | finish]
3090: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61   all [sqlite3_ba
30a0: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73  ckup] objects as
30b0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
30c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
30d0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
30e0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
30f0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
3100: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
3110: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
3120: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
3130: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
3140: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
3150: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
3160: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3170: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3180: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
3190: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
31a0: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
31b0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
31c0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c  K] and the deall
31d0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
31e0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
31f0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
3200: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
3210: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
3220: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
3230: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
3240: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
3250: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
3260: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
3270: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
3280: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
3290: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
32a0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
32b0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
32c0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
32d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
32e0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
32f0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
3300: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
3310: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
3320: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
3330: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
3340: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
3350: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
3360: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3370: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
3380: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
3390: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
33a0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
33b0: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
33c0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
33d0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
33e0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
33f0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
3400: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
3410: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
3420: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
3430: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
3440: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69  ose(sqlite3*);.i
3450: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3460: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
3470: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
3480: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
3490: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
34a0: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
34b0: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
34c0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
34d0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
34e0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
34f0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
3500: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
3510: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
3520: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3530: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
3540: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3550: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
3560: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
3570: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
3580: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
3590: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
35a0: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
35b0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
35c0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
35d0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
35e0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
35f0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
3600: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
3610: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3620: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3630: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3640: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3650: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3660: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3670: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3680: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3690: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
36a0: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
36b0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
36c0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
36d0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
36e0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
36f0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
3700: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
3710: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3720: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3730: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3740: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3750: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3760: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3770: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3780: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3790: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
37a0: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
37b0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
37c0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
37d0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
37e0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
37f0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
3800: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3810: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3820: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3830: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3840: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3850: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3860: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3870: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3880: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3890: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
38a0: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
38b0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
38c0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
38d0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
38e0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
38f0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
3900: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
3910: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3920: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3940: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3950: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3960: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3970: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3980: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3990: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
39a0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
39b0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
39c0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
39d0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
39e0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
39f0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
3a00: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3a10: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3a20: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3a30: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3a40: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3a50: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3a60: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3a70: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3a80: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3a90: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3aa0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3ab0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
3ac0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
3ad0: 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  eter of.** sqlit
3ae0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20  e3_exec() after 
3af0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
3b00: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c  e string is no l
3b10: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3b20: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3b30: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3b40: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3b50: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f  NULL and no erro
3b60: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65  rs.** occur, the
3b70: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3b80: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65   sets the pointe
3b90: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72  r in its 5th par
3ba0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c  ameter to.** NUL
3bb0: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  L before returni
3bc0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ng..**.** ^If an
3bd0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3be0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
3bf0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73   non-zero, the s
3c00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3c10: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
3c20: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69   SQLITE_ABORT wi
3c30: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74  thout invoking t
3c40: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69  he callback agai
3c50: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74  n and.** without
3c60: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62   running any sub
3c70: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
3c80: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
3c90: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20  he 2nd argument 
3ca0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3cb0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66  xec() callback f
3cc0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a  unction is the.*
3cd0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  * number of colu
3ce0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
3cf0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67  t.  ^The 3rd arg
3d00: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3d10: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63  ite3_exec().** c
3d20: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
3d30: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3d40: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69  to strings obtai
3d50: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a  ned as if from.*
3d60: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
3d70: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66  n_text()], one f
3d80: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20  or each column. 
3d90: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20   ^If an element 
3da0: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72  of a.** result r
3db0: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ow is NULL then 
3dc0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
3dd0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  g string pointer
3de0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69   for the.** sqli
3df0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3e00: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ack is a NULL po
3e10: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68  inter.  ^The 4th
3e20: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e30: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3e40: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3e50: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e60: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
3e70: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74  here each.** ent
3e80: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68  ry represents th
3e90: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73  e name of corres
3ea0: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63  ponding result c
3eb0: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65  olumn as obtaine
3ec0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3ed0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
3ee0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
3ef0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
3f00: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3f10: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3f20: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  er, a pointer.**
3f30: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
3f40: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65  ing, or a pointe
3f50: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  r that contains 
3f60: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20  only whitespace 
3f70: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63  and/or .** SQL c
3f80: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
3f90: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3fa0: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
3fb0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  d the database.*
3fc0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
3fd0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74  ..**.** Restrict
3fe0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ions:.**.** <ul>
3ff0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
4000: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e  lication must en
4010: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73  sure that the 1s
4020: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
4030: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
4040: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64        is a valid
4050: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62   and open [datab
4060: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
4070: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
4080: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
4090: 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74  t close the [dat
40a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
40b0: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
40c0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
40d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
40e0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
40f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4100: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
4110: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4120: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
4130: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
4140: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
4150: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
4160: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
4170: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
4180: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
4190: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
41a0: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
41b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
41c0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
41f0: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
4200: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
4210: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4230: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
4240: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
4250: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
4260: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
4270: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
4280: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
4290: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
42c0: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
42d0: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
42e0: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4300: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
4310: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
4320: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
4330: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
4340: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4350: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
4360: 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a  de definitions}.
4370: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
4380: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
4390: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
43a0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
43b0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
43c0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
43d0: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73   indicate succes
43e0: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
43f0: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f  .** New error co
4400: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  des may be added
4410: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
4420: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
4430: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
4440: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4450: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  code definitions
4460: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ].*/.#define SQL
4470: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
4480: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4490: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
44a0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
44b0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
44c0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
44d0: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
44e0: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
44f0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4510: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4520: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
4530: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
4540: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4550: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
4560: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
4570: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
4580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4590: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
45a0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
45b0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
45c0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
45d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
45e0: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
45f0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4600: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4610: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4620: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4630: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4640: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4650: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4660: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
4670: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
4680: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4690: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
46a0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
46b0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
46c0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
46d0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
46e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
46f0: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4700: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4710: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4720: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4730: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4740: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4750: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4760: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
4770: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
4780: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4790: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
47a0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
47b0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
47c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
47d0: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
47e0: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
47f0: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4800: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4820: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4830: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4840: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4850: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4870: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
4880: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4890: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
48a0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
48b0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
48c0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
48d0: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
48e0: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
48f0: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4900: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4910: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4920: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4930: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4940: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4950: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4960: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4970: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
4980: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4990: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
49a0: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
49b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
49c0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
49d0: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
49e0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
49f0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4a00: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4a10: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4a20: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4a30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4a40: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4a50: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4a60: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
4a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
4a80: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4a90: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4aa0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4ab0: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
4ac0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4ad0: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4ae0: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4af0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4b00: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4b10: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4b20: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4b30: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4b40: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4b50: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4b60: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4b70: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4b80: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4b90: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4ba0: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4bb0: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4bc0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4bd0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4be0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20  e SQLITE_NOTICE 
4bf0: 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74       27   /* Not
4c00: 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20  ifications from 
4c10: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4c20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c30: 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20  WARNING     28  
4c40: 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f   /* Warnings fro
4c50: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
4c60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4c70: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
4c80: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
4c90: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
4ca0: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
4cb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
4cc0: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
4cd0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4ce0: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
4cf0: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
4d00: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4d10: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
4d20: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
4d30: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
4d40: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
4d50: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66   result code def
4d60: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  initions}.**.** 
4d70: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4d80: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4d90: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4da0: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4db0: 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72  30 integer.** [r
4dc0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48  esult codes].  H
4dd0: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e  owever, experien
4de0: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61  ce has shown tha
4df0: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65  t many of.** the
4e00: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  se result codes 
4e10: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67  are too coarse-g
4e20: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f  rained.  They do
4e30: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a   not provide as.
4e40: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74  ** much informat
4e50: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65  ion about proble
4e60: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72  ms as programmer
4e70: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49  s might like.  I
4e80: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a  n an effort to.*
4e90: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20  * address this, 
4ea0: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
4eb0: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f  f SQLite (versio
4ec0: 6e 20 33 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a  n 3.3.8 [dateof:
4ed0: 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61  3.3.8].** and la
4ee0: 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20  ter) include.** 
4ef0: 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69  support for addi
4f00: 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f  tional result co
4f10: 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65  des that provide
4f20: 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69   more detailed i
4f30: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
4f40: 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73  out errors. Thes
4f50: 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  e [extended resu
4f60: 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e  lt codes] are en
4f70: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4f80: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4f90: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4fa0: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4fb0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4fc0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
4fd0: 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c  des()] API.  Or,
4fe0: 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f   the extended co
4ff0: 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f  de for.** the mo
5000: 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20  st recent error 
5010: 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
5020: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
5030: 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
5040: 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  de()]..*/.#defin
5050: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
5060: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
5070: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5080: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5090: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
50a0: 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20  ORT_READ        
50b0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
50c0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
50d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49  SQLITE_IOERR_WRI
50e0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  TE             (
50f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5100: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5110: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e  QLITE_IOERR_FSYN
5120: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  C             (S
5130: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34  QLITE_IOERR | (4
5140: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5150: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46  LITE_IOERR_DIR_F
5160: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51  SYNC         (SQ
5170: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c  LITE_IOERR | (5<
5180: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5190: 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41  ITE_IOERR_TRUNCA
51a0: 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TE          (SQL
51b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c  ITE_IOERR | (6<<
51c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51d0: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20  TE_IOERR_FSTAT  
51e0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
51f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38  TE_IOERR | (7<<8
5200: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5210: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20  E_IOERR_UNLOCK  
5220: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5230: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29  E_IOERR | (8<<8)
5240: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5250: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20  _IOERR_RDLOCK   
5260: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5270: 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29  _IOERR | (9<<8))
5280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5290: 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20  IOERR_DELETE    
52a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
52b0: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29  IOERR | (10<<8))
52c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52d0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20  IOERR_BLOCKED   
52e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
52f0: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29  IOERR | (11<<8))
5300: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5310: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20  IOERR_NOMEM     
5320: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5330: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29  IOERR | (12<<8))
5340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5350: 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20  IOERR_ACCESS    
5360: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5370: 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29  IOERR | (13<<8))
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5390: 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52  IOERR_CHECKRESER
53a0: 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f  VEDLOCK (SQLITE_
53b0: 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29  IOERR | (14<<8))
53c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53d0: 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20  IOERR_LOCK      
53e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
53f0: 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29  IOERR | (15<<8))
5400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5410: 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20  IOERR_CLOSE     
5420: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5430: 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29  IOERR | (16<<8))
5440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5450: 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20  IOERR_DIR_CLOSE 
5460: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5470: 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29  IOERR | (17<<8))
5480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5490: 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20  IOERR_SHMOPEN   
54a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
54b0: 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29  IOERR | (18<<8))
54c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54d0: 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20  IOERR_SHMSIZE   
54e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
54f0: 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29  IOERR | (19<<8))
5500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5510: 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20  IOERR_SHMLOCK   
5520: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5530: 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29  IOERR | (20<<8))
5540: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5550: 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20  IOERR_SHMMAP    
5560: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5570: 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29  IOERR | (21<<8))
5580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5590: 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20  IOERR_SEEK      
55a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
55b0: 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29  IOERR | (22<<8))
55c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55d0: 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45  IOERR_DELETE_NOE
55e0: 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  NT      (SQLITE_
55f0: 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29  IOERR | (23<<8))
5600: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5610: 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20  IOERR_MMAP      
5620: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5630: 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29  IOERR | (24<<8))
5640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5650: 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54  IOERR_GETTEMPPAT
5660: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
5670: 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29  IOERR | (25<<8))
5680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5690: 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20  IOERR_CONVPATH  
56a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56b0: 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29  IOERR | (26<<8))
56c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56d0: 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20 20  IOERR_VNODE     
56e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56f0: 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29 29  IOERR | (27<<8))
5700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5710: 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20 20 20  IOERR_AUTH      
5720: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5730: 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 29 29  IOERR | (28<<8))
5740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5750: 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43  LOCKED_SHAREDCAC
5760: 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  HE      (SQLITE_
5770: 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29  LOCKED |  (1<<8)
5780: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5790: 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20  _BUSY_RECOVERY  
57a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
57b0: 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38  _BUSY   |  (1<<8
57c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
57d0: 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20  E_BUSY_SNAPSHOT 
57e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
57f0: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c  E_BUSY   |  (2<<
5800: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5810: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45  TE_CANTOPEN_NOTE
5820: 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49  MPDIR      (SQLI
5830: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31  TE_CANTOPEN | (1
5840: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5850: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53  LITE_CANTOPEN_IS
5860: 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51  DIR          (SQ
5870: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5880: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5890: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
58a0: 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28  FULLPATH       (
58b0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
58c0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
58d0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
58e0: 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20  N_CONVPATH      
58f0: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5900: 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  N | (4<<8)).#def
5910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
5920: 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  PT_VTAB         
5930: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55     (SQLITE_CORRU
5940: 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  PT | (1<<8)).#de
5950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5960: 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20  ONLY_RECOVERY   
5970: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5980: 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23  ONLY | (1<<8)).#
5990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
59a0: 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20  ADONLY_CANTLOCK 
59b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
59c0: 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29  ADONLY | (2<<8))
59d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59e0: 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43  READONLY_ROLLBAC
59f0: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
5a00: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38  READONLY | (3<<8
5a10: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a20: 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56  E_READONLY_DBMOV
5a30: 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ED        (SQLIT
5a40: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c  E_READONLY | (4<
5a50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a60: 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41  ITE_ABORT_ROLLBA
5a70: 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  CK          (SQL
5a80: 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c  ITE_ABORT | (2<<
5a90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5aa0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48  TE_CONSTRAINT_CH
5ab0: 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49  ECK        (SQLI
5ac0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5ad0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5ae0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5af0: 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28  T_COMMITHOOK   (
5b00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b10: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
5b20: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5b30: 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59  RAINT_FOREIGNKEY
5b40: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5b50: 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a  RAINT | (3<<8)).
5b60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b70: 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49  ONSTRAINT_FUNCTI
5b80: 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  ON     (SQLITE_C
5b90: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c  ONSTRAINT | (4<<
5ba0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5bb0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f  TE_CONSTRAINT_NO
5bc0: 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49  TNULL      (SQLI
5bd0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5be0: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
5bf0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c00: 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28  T_PRIMARYKEY   (
5c10: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c20: 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  T | (6<<8)).#def
5c30: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5c40: 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20  RAINT_TRIGGER   
5c50: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5c60: 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a  RAINT | (7<<8)).
5c70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5c80: 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45  ONSTRAINT_UNIQUE
5c90: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5ca0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c  ONSTRAINT | (8<<
5cb0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5cc0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54  TE_CONSTRAINT_VT
5cd0: 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  AB         (SQLI
5ce0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5cf0: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5d00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5d10: 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28  T_ROWID        (
5d20: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5d30: 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66  T |(10<<8)).#def
5d40: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
5d50: 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20  E_RECOVER_WAL   
5d60: 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43     (SQLITE_NOTIC
5d70: 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  E | (1<<8)).#def
5d80: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
5d90: 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41  E_RECOVER_ROLLBA
5da0: 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43  CK (SQLITE_NOTIC
5db0: 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  E | (2<<8)).#def
5dc0: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
5dd0: 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20  NG_AUTOINDEX    
5de0: 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49     (SQLITE_WARNI
5df0: 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NG | (1<<8)).#de
5e00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
5e10: 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20  _USER           
5e20: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48      (SQLITE_AUTH
5e30: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5e40: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41  ne SQLITE_OK_LOA
5e50: 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20  D_PERMANENTLY   
5e60: 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28    (SQLITE_OK | (
5e70: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  1<<8))../*.** CA
5e80: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
5e90: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
5ea0: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
5eb0: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
5ec0: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
5ed0: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
5ee0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5ef0: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
5f00: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
5f10: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
5f20: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
5f30: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
5f40: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
5f50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f60: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
5f70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5f80: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
5f90: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5fa0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5fb0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
5fc0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5fd0: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
5fe0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ff0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6000: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
6010: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6020: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
6030: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6040: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6050: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
6060: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
6070: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
6080: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6090: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
60a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
60b0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
60c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60d0: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
60e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
60f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6100: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6110: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
6120: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
6130: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6140: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6150: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6160: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20  _OPEN_MEMORY    
6170: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
6180: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6190: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
61a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61b0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
61c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
61d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
61e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61f0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
6200: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6210: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6220: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6230: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
6240: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
6250: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6270: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
6280: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
6290: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
62a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62b0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
62c0: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
62d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
62e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62f0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
6300: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
6310: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6320: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6330: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
6340: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
6350: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6360: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6370: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
6380: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
6390: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
63a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
63b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
63c0: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
63d0: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
63e0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
63f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6400: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6410: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
6420: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
6430: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6440: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6450: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6460: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
6470: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
6480: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6490: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
64a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
64b0: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
64c0: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
64d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
64e0: 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20  /../* Reserved: 
64f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6500: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30          0x00F000
6510: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00 */../*.** CAP
6520: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
6530: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a  aracteristics.**
6540: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
6550: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
6560: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
6570: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6580: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
6590: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
65a0: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
65b0: 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74   of these.** bit
65c0: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69   values expressi
65d0: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72  ng I/O character
65e0: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61  istics of the ma
65f0: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65  ss storage.** de
6600: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20  vice that holds 
6610: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68  the file that th
6620: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6630: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73  thods].** refers
6640: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53   to..**.** The S
6650: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6660: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
6670: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
6680: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
6690: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
66a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
66b0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
66c0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
66d0: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
66e0: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
66f0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
6700: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
6710: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
6720: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
6730: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
6740: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6750: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6760: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
6770: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
6780: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
6790: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
67a0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
67b0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
67c0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
67d0: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
67e0: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
67f0: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
6800: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
6810: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6820: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6830: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
6840: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
6850: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
6860: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
6870: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
6880: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6890: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
68a0: 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79  ERWRITE property
68b0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61   means that.** a
68c0: 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c  fter reboot foll
68d0: 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72  owing a crash or
68e0: 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65   power loss, the
68f0: 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61   only bytes in a
6900: 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65  .** file that we
6910: 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68  re written at th
6920: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65  e application le
6930: 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63  vel might have c
6940: 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68  hanged.** and th
6950: 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65  at adjacent byte
6960: 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69  s, even bytes wi
6970: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65  thin the same se
6980: 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72  ctor are.** guar
6990: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63  anteed to be unc
69a0: 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c  hanged.  The SQL
69b0: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
69c0: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a  TABLE_WHEN_OPEN.
69d0: 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65  ** flag indicate
69e0: 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61  s that a file ca
69f0: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20  nnot be deleted 
6a00: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a  when open.  The.
6a10: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ** SQLITE_IOCAP_
6a20: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69  IMMUTABLE flag i
6a30: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
6a40: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20  e file is on.** 
6a50: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20  read-only media 
6a60: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  and cannot be ch
6a70: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72  anged even by pr
6a80: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20  ocesses with.** 
6a90: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65  elevated privile
6aa0: 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ges..*/.#define 
6ab0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6ac0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
6ad0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
6ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6af0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
6b00: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6b10: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
6b20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6b30: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
6b40: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
6b50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b60: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
6b70: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6b80: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
6b90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
6ba0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6bb0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
6bc0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6bd0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
6be0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
6bf0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6c00: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6c10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6c20: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
6c30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6c40: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
6c50: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
6c60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6c70: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
6c80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6c90: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
6ca0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6cb0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
6cc0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
6cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6ce0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
6cf0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6d00: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
6d10: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6d20: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
6d30: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
6d40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6d50: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
6d60: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30  RITE    0x000010
6d70: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6d80: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
6d90: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  E              0
6da0: 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00002000../*.**
6db0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
6dc0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
6dd0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
6de0: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
6df0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6e00: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
6e10: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
6e20: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
6e30: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
6e40: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
6e50: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6e60: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6e70: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
6e80: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
6e90: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
6ea0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
6eb0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
6ec0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6ed0: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
6ee0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
6ef0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
6f00: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
6f10: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6f20: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
6f30: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
6f40: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
6f50: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
6f60: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
6f70: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
6f80: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
6f90: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6fa0: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
6fb0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
6fc0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
6fd0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6fe0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
6ff0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
7000: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
7010: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
7020: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
7030: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
7040: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
7050: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
7060: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
7070: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
7080: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
7090: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
70a0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
70b0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
70c0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
70d0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
70e0: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
70f0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
7100: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
7110: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
7120: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
7130: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
7140: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
7150: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
7160: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
7170: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
7180: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
7190: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
71a0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
71b0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
71c0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
71d0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
71e0: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
71f0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
7200: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
7210: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
7220: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
7230: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
7240: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
7250: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
7260: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
7270: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
7280: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
7290: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
72a0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
72b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
72c0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
72d0: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
72e0: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
72f0: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
7300: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
7310: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
7320: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
7330: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
7340: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
7350: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
7360: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
7370: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
7380: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
7390: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
73a0: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
73b0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
73c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
73d0: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
73e0: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
73f0: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
7400: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
7410: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
7420: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
7430: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
7440: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7450: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
7460: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
7470: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7480: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
7490: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
74a0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
74b0: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
74c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
74d0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
74e0: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
74f0: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
7500: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
7510: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
7520: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
7530: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
7540: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
7550: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
7560: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
7570: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7580: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
7590: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
75a0: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
75b0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
75c0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
75d0: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
75e0: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
75f0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
7600: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
7610: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7620: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
7630: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
7640: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
7650: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
7660: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
7670: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7680: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
7690: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
76a0: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
76b0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
76c0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
76d0: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
76e0: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
76f0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
7700: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7710: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
7720: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
7730: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
7740: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
7750: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7760: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
7770: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
7780: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7790: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
77a0: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
77b0: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
77c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
77d0: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
77e0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
77f0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
7800: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
7810: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
7820: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
7830: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
7840: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
7850: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
7860: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
7870: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
7880: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
7890: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
78a0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
78b0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
78c0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
78d0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
78e0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
78f0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
7900: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7910: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
7920: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
7930: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
7940: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7950: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
7960: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
7970: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
7980: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
7990: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
79a0: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
79b0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
79c0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
79d0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
79e0: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
79f0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7a00: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
7a10: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
7a20: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7a30: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
7a40: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
7a50: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
7a60: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
7a70: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
7a80: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
7a90: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
7aa0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
7ab0: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
7ac0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
7ad0: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
7ae0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
7af0: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
7b00: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
7b10: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
7b20: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
7b30: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
7b40: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
7b50: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
7b60: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
7b70: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
7b80: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
7b90: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
7ba0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7bb0: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
7bc0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
7bd0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
7be0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
7bf0: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
7c00: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7c10: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
7c20: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
7c30: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
7c40: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
7c50: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
7c60: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
7c70: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
7c80: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
7c90: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
7ca0: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
7cb0: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
7cc0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
7cd0: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
7ce0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
7cf0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
7d00: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
7d10: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
7d20: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
7d30: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
7d40: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
7d50: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
7d60: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
7d70: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
7d80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
7d90: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
7da0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
7db0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
7dc0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
7dd0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7de0: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
7df0: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
7e00: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
7e10: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
7e20: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
7e30: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
7e40: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
7e50: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
7e60: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
7e70: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
7e80: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
7e90: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
7ea0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
7eb0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
7ec0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
7ed0: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
7ee0: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
7ef0: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
7f00: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
7f10: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7f20: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
7f30: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
7f40: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
7f50: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
7f60: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
7f70: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
7f80: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
7f90: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
7fa0: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
7fb0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
7fc0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
7fd0: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
7fe0: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
7ff0: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
8000: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
8010: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
8020: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
8030: 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f  * A [file contro
8040: 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74  l opcodes | list
8050: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
8060: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
8070: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
8080: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
8090: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
80a0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
80b0: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
80c0: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
80d0: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
80e0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
80f0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
8100: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
8110: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
8120: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
8130: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
8140: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
8150: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
8160: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
8170: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
8180: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
8190: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
81a0: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
81b0: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
81c0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
81d0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
81e0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
81f0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
8200: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
8210: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
8220: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
8230: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
8240: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
8250: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
8260: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
8270: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
8280: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
8290: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
82a0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
82b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
82c0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
82d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
82e0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
82f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8300: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
8310: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8320: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
8330: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8340: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
8350: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8360: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
8370: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8380: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
8390: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
83a0: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
83b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
83c0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
83d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
83e0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
83f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8400: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
8410: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8420: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57  AP_UNDELETABLE_W
8430: 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69  HEN_OPEN].** <li
8440: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8450: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
8460: 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ITE].** <li> [SQ
8470: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
8480: 41 42 4c 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ABLE].** </ul>.*
8490: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
84a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
84b0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
84c0: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
84d0: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
84e0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
84f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
8500: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
8510: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
8520: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
8530: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
8540: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
8550: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
8560: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
8570: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
8580: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
8590: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
85a0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
85b0: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
85c0: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
85d0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
85e0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
85f0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
8600: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
8610: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
8620: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
8630: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
8640: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
8650: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8660: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
8670: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
8680: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
8690: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
86a0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
86b0: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
86c0: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
86d0: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
86e0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
86f0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
8700: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
8710: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
8720: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
8730: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
8740: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
8750: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
8760: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8770: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
8780: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
8790: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
87a0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
87b0: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
87c0: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
87d0: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
87e0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
87f0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8800: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
8810: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
8820: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8830: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
8840: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
8850: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
8860: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8870: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
8880: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
8890: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
88a0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
88b0: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
88c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
88d0: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
88e0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
88f0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8900: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
8910: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8920: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
8930: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
8940: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8950: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
8960: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
8970: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8980: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
8990: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
89a0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
89b0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
89c0: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
89d0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
89e0: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
89f0: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
8a00: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
8a10: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
8a20: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
8a30: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8a40: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
8a50: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
8a60: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
8a70: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
8a80: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8a90: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
8aa0: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  le*);.  /* Metho
8ab0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8ac0: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31  id for version 1
8ad0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
8ae0: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  Map)(sqlite3_fil
8af0: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74  e*, int iPg, int
8b00: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64   pgsz, int, void
8b10: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20   volatile**);.  
8b20: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28  int (*xShmLock)(
8b30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8b40: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e  nt offset, int n
8b50: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8b60: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69  void (*xShmBarri
8b70: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  er)(sqlite3_file
8b80: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8b90: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  Unmap)(sqlite3_f
8ba0: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65  ile*, int delete
8bb0: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  Flag);.  /* Meth
8bc0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8bd0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8be0: 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65  2 */.  int (*xFe
8bf0: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
8c00: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8c10: 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d  4 iOfst, int iAm
8c20: 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20  t, void **pp);. 
8c30: 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29   int (*xUnfetch)
8c40: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8c50: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
8c60: 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20  fst, void *p);. 
8c70: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8c80: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8c90: 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f  version 3 */.  /
8ca0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
8cb0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
8cc0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
8cd0: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
8ce0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
8cf0: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
8d00: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59  l Opcodes.** KEY
8d10: 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e  WORDS: {file con
8d20: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66  trol opcodes} {f
8d30: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
8d40: 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  de}.**.** These 
8d50: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
8d60: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
8d70: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
8d80: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
8d90: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
8da0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
8db0: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
8dc0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8dd0: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
8de0: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e..**.** <ul>.**
8df0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8e00: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a  NTL_LOCKSTATE]].
8e10: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8e20: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
8e30: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
8e40: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
8e50: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
8e60: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
8e70: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
8e80: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
8e90: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
8ea0: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
8eb0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
8ec0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
8ed0: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
8ee0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
8ef0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
8f00: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
8f10: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
8f20: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
8f30: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
8f40: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
8f50: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
8f60: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
8f70: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
8f80: 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c  sting and is onl
8f90: 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e  y available when
8fa0: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54   the SQLITE_TEST
8fb0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
8fc0: 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
8fd0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8fe0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
8ff0: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  INT]].** The [SQ
9000: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9010: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20  HINT] opcode is 
9020: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74  used by SQLite t
9030: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a  o give the VFS.*
9040: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f  * layer a hint o
9050: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20  f how large the 
9060: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
9070: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75  ll grow to be du
9080: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72  ring the.** curr
9090: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  ent transaction.
90a0: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e    This hint is n
90b0: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ot guaranteed to
90c0: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74   be accurate but
90d0: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20   it.** is often 
90e0: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65  close.  The unde
90f0: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74  rlying VFS might
9100: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c   choose to preal
9110: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a  locate database.
9120: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61  ** file space ba
9130: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  sed on this hint
9140: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c   in order to hel
9150: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20  p writes to the 
9160: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
9170: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a   run faster..**.
9180: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9190: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
91a0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
91b0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
91c0: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ZE] opcode is us
91d0: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68  ed to request th
91e0: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78  at the VFS.** ex
91f0: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61  tends and trunca
9200: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  tes the database
9210: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20   file in chunks 
9220: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66  of a size specif
9230: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73  ied.** by the us
9240: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61  er. The fourth a
9250: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
9260: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9270: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70  ()] should .** p
9280: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67  oint to an integ
9290: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f  er (type int) co
92a0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77  ntaining the new
92b0: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75   chunk-size to u
92c0: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f  se.** for the no
92d0: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65  minated database
92e0: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74  . Allocating dat
92f0: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65  abase file space
9300: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75   in large.** chu
9310: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20  nks (say 1MB at 
9320: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64  a time), may red
9330: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20  uce file-system 
9340: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  fragmentation an
9350: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72  d.** improve per
9360: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65  formance on some
9370: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20   systems..**.** 
9380: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9390: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
93a0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
93b0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
93c0: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TER] opcode is u
93d0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20  sed to obtain a 
93e0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
93f0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
9400: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74   object associat
9410: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ed with a partic
9420: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
9430: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
9440: 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46  e also [SQLITE_F
9450: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
9460: 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  NTER]..**.** <li
9470: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9480: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
9490: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
94a0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
94b0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
94c0: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
94d0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
94e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
94f0: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
9500: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a  iated with the j
9510: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74  ournal file (eit
9520: 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c  her.** the [roll
9530: 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72  back journal] or
9540: 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61   the [write-ahea
9550: 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61  d log]) for a pa
9560: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
9570: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
9580: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49    See also [SQLI
9590: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
95a0: 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  INTER]..**.** <l
95b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
95c0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
95d0: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20  ** No longer in 
95e0: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  use..**.** <li>[
95f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9600: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NC]].** The [SQL
9610: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20  ITE_FCNTL_SYNC] 
9620: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9630: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9640: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20  y SQLite and.** 
9650: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9660: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
9670: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  re the xSync met
9680: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hod is invoked o
9690: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  n a.** database 
96a0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e  file descriptor.
96b0: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e   Or, if the xSyn
96c0: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20  c method is not 
96d0: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61  invoked .** beca
96e0: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73  use the user has
96f0: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69   configured SQLi
9700: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41  te with .** [PRA
9710: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20  GMA synchronous 
9720: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f  | PRAGMA synchro
9730: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20  nous=OFF] it is 
9740: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65  invoked in place
9750: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e   .** of the xSyn
9760: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73  c method. In mos
9770: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69  t cases, the poi
9780: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61  nter argument pa
9790: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69  ssed with.** thi
97a0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
97b0: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c  s NULL. However,
97c0: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
97d0: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73   file is being s
97e0: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  ynced.** as part
97f0: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61   of a multi-data
9800: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65  base commit, the
9810: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
9820: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   to a nul-termin
9830: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63  ated.** string c
9840: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72  ontaining the tr
9850: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65  ansactions maste
9860: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e  r-journal file n
9870: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20  ame. VFSes that 
9880: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  .** do not need 
9890: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75  this signal shou
98a0: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
98b0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
98c0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a  Applications .**
98d0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
98e0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
98f0: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
9900: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
9910: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64  ing so may .** d
9920: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
9930: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9940: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
9950: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9960: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
9970: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
9980: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a  MIT_PHASETWO]].*
9990: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
99a0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
99b0: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TWO] opcode is g
99c0: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
99d0: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  lly by SQLite.**
99e0: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65   and sent to the
99f0: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61   VFS after a tra
9a00: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65  nsaction has bee
9a10: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65  n committed imme
9a20: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62  diately.** but b
9a30: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61  efore the databa
9a40: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20  se is unlocked. 
9a50: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  VFSes that do no
9a60: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9a70: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c  al.** should sil
9a80: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9a90: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9aa0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9ab0: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
9ac0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9ad0: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
9ae0: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
9af0: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
9b00: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  .** operation of
9b10: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9b20: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
9b30: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
9b40: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9b50: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
9b60: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
9b70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9b80: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
9b90: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
9ba0: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
9bb0: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
9bc0: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
9bd0: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
9be0: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
9bf0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
9c00: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
9c10: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
9c20: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
9c30: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
9c40: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
9c50: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
9c60: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
9c70: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
9c80: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
9c90: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
9ca0: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
9cb0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
9cc0: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
9cd0: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
9ce0: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
9cf0: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
9d00: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
9d10: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
9d20: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
9d30: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
9d40: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
9d50: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
9d60: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
9d70: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
9d80: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
9d90: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9da0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
9db0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
9dc0: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
9dd0: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
9de0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
9df0: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
9e00: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
9e10: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
9e20: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9e30: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
9e40: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
9e50: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
9e60: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
9e70: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
9e80: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
9e90: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
9ea0: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
9eb0: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
9ec0: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
9ed0: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
9ee0: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
9ef0: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
9f00: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
9f10: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
9f20: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
9f30: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
9f40: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
9f50: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
9f60: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
9f70: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
9f80: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
9f90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9fa0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9fb0: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
9fc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9fd0: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
9fe0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9ff0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a000: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
a010: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
a020: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
a030: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
a040: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
a050: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
a060: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
a070: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
a080: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
a090: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
a0a0: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
a0b0: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
a0c0: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
a0d0: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
a0e0: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
a0f0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
a100: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
a110: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
a120: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
a130: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
a140: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
a150: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
a160: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
a170: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
a180: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
a190: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
a1a0: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
a1b0: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
a1c0: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
a1d0: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
a1e0: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
a1f0: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
a200: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
a210: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
a220: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
a230: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
a240: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
a250: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a260: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
a270: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
a280: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
a290: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
a2a0: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
a2b0: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
a2c0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
a2d0: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
a2e0: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
a2f0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a300: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a310: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a320: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a330: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
a340: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
a350: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a360: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
a370: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
a380: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
a390: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
a3a0: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
a3b0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
a3c0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
a3d0: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
a3e0: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
a3f0: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
a400: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
a410: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
a420: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
a430: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
a440: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
a450: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
a460: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
a470: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
a480: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a490: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a4a0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a4b0: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a4c0: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a4d0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a4e0: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a4f0: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a500: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
a510: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a520: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
a530: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a540: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a550: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a560: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a570: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
a580: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
a590: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a5a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a5b0: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
a5c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
a5d0: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
a5e0: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
a5f0: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
a600: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
a610: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
a620: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
a630: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
a640: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
a650: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
a660: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
a670: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
a680: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
a690: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
a6a0: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
a6b0: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
a6c0: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
a6d0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a6e0: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
a6f0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a700: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
a710: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
a720: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
a730: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
a740: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
a750: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
a760: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
a770: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
a780: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
a790: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
a7a0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
a7b0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
a7c0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
a7d0: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
a7e0: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
a7f0: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a800: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
a810: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a820: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
a830: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
a840: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
a850: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
a860: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
a870: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
a880: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
a890: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
a8a0: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
a8b0: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
a8c0: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
a8d0: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
a8e0: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
a8f0: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
a900: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
a910: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
a920: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
a930: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
a940: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
a950: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
a960: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
a970: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
a980: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
a990: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
a9a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
a9b0: 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  FS_POINTER]].** 
a9c0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a9d0: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20  TL_VFS_POINTER] 
a9e0: 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70  opcode finds a p
a9f0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f  ointer to the to
aa00: 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65  p-level.** [VFSe
aa10: 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20  s] currently in 
aa20: 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75  use.  ^(The argu
aa30: 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c  ment X in.** sql
aa40: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
aa50: 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54  l(db,SQLITE_FCNT
aa60: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29  L_VFS_POINTER,X)
aa70: 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74   must be.** of t
aa80: 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66  ype "[sqlite3_vf
aa90: 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70  s] **".  This op
aaa0: 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a  codes will set *
aab0: 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65  X.** to a pointe
aac0: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
aad0: 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68  el VFS.)^.** ^Wh
aae0: 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c  en there are mul
aaf0: 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20  tiple VFS shims 
ab00: 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68  in the stack, th
ab10: 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20  is opcode finds 
ab20: 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73  the.** upper-mos
ab30: 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a  t shim only..**.
ab40: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ab50: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a  FCNTL_PRAGMA]].*
ab60: 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50  * ^Whenever a [P
ab70: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
ab80: 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b   is parsed, an [
ab90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
aba0: 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f  GMA] .** file co
abb0: 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f  ntrol is sent to
abc0: 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74   the open [sqlit
abd0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
abe0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
abf0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
ac00: 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74   file to which t
ac10: 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  he pragma statem
ac20: 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65  ent refers. ^The
ac30: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
ac40: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
ac50: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
ac60: 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72  ontrol is an arr
ac70: 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72  ay of.** pointer
ac80: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68  s to strings (ch
ac90: 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74  ar**) in which t
aca0: 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e  he second elemen
acb0: 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a  t of the array.*
acc0: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
acd0: 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20   the pragma and 
ace0: 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e  the third elemen
acf0: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
ad00: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67  t to the.** prag
ad10: 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  ma or NULL if th
ad20: 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20  e pragma has no 
ad30: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20  argument.  ^The 
ad40: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a  handler for an.*
ad50: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
ad60: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
ad70: 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61  trol can optiona
ad80: 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72  lly make the fir
ad90: 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66  st element.** of
ada0: 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75   the char** argu
adb0: 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20  ment point to a 
adc0: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
add0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
ade0: 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74  rintf()].** or t
adf0: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  he equivalent an
ae00: 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69  d that string wi
ae10: 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65  ll become the re
ae20: 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67  sult of the prag
ae30: 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72  ma or.** the err
ae40: 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68  or message if th
ae50: 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20  e pragma fails. 
ae60: 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
ae70: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
ae80: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
ae90: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f  turns [SQLITE_NO
aea0: 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f  TFOUND], then no
aeb0: 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  rmal .** [PRAGMA
aec0: 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e  ] processing con
aed0: 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65  tinues.  ^If the
aee0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
aef0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
af00: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
af10: 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e  SQLITE_OK], then
af20: 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75   the parser assu
af30: 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
af40: 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20  VFS has handled 
af50: 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c  the PRAGMA itsel
af60: 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72  f and the parser
af70: 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d   generates a no-
af80: 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  op.** prepared s
af90: 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75  tatement if resu
afa0: 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c  lt string is NUL
afb0: 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72  L, or that retur
afc0: 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  ns a copy.** of 
afd0: 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e  the result strin
afe0: 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  g if the string 
aff0: 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20  is non-NULL..** 
b000: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
b010: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
b020: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
b030: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74  ns.** any result
b040: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e   code other than
b050: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
b060: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
b070: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  ], that means.**
b080: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e   that the VFS en
b090: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72  countered an err
b0a0: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e  or while handlin
b0b0: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61  g the [PRAGMA] a
b0c0: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  nd the.** compil
b0d0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41  ation of the PRA
b0e0: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61  GMA fails with a
b0f0: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b  n error.  ^The [
b100: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b110: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
b120: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74  trol occurs at t
b130: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
b140: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
b150: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f   analysis and so
b160: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74  .** it is able t
b170: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74  o override built
b180: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  -in [PRAGMA] sta
b190: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c  tements..**.** <
b1a0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b1b0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a  L_BUSYHANDLER]].
b1c0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
b1d0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
b1e0: 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  R].** file-contr
b1f0: 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ol may be invoke
b200: 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74  d by SQLite on t
b210: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
b220: 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74   handle.** short
b230: 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f  ly after it is o
b240: 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  pened in order t
b250: 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74  o provide a cust
b260: 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65  om VFS with acce
b270: 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e  ss.** to the con
b280: 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61  nections busy-ha
b290: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  ndler callback. 
b2a0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
b2b0: 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a  of type (void **
b2c0: 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20  ).** - an array 
b2d0: 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20  of two (void *) 
b2e0: 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73  values. The firs
b2f0: 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61  t (void *) actua
b300: 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f  lly points.** to
b310: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
b320: 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69  ype (int (*)(voi
b330: 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20  d *)). In order 
b340: 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f  to invoke the co
b350: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73  nnections.** bus
b360: 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20  y-handler, this 
b370: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
b380: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
b390: 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64  the second (void
b3a0: 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72   *) in.** the ar
b3b0: 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ray as the only 
b3c0: 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20  argument. If it 
b3d0: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
b3e0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61  , then the opera
b3f0: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
b400: 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74  e retried. If it
b410: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
b420: 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68  he custom VFS sh
b430: 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65  ould abandon the
b440: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72  .** current oper
b450: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
b460: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b470: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a  TEMPFILENAME]].*
b480: 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63  * ^Application c
b490: 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53  an invoke the [S
b4a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
b4b0: 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63  FILENAME] file-c
b4c0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76  ontrol.** to hav
b4d0: 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74  e SQLite generat
b4e0: 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  e a.** temporary
b4f0: 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20   filename using 
b500: 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
b510: 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f  hm that is follo
b520: 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a  wed to generate.
b530: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
b540: 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20  enames for TEMP 
b550: 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72  tables and other
b560: 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20   internal uses. 
b570: 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   The.** argument
b580: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61   should be a cha
b590: 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62  r** which will b
b5a0: 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  e filled with th
b5b0: 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72  e filename.** wr
b5c0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
b5d0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
b5e0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
b5f0: 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20  )].  The caller 
b600: 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65  should.** invoke
b610: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
b620: 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20  ] on the result 
b630: 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72  to avoid a memor
b640: 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  y leak..**.** <l
b650: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b660: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
b670: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b680: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
b690: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e control is use
b6a0: 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65  d to query or se
b6b0: 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d  t the.** maximum
b6c0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
b6d0: 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73   that will be us
b6e0: 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61  ed for memory-ma
b6f0: 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65  pped I/O..** The
b700: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
b710: 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75  ointer to a valu
b720: 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65  e of type sqlite
b730: 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20  3_int64 that.** 
b740: 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d  is an advisory m
b750: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
b760: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
b770: 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70  le to memory map
b780: 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  .  The.** pointe
b790: 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  r is overwritten
b7a0: 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61   with the old va
b7b0: 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20  lue.  The limit 
b7c0: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69  is not changed i
b7d0: 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f  f.** the value o
b7e0: 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65  riginally pointe
b7f0: 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65  d to is negative
b800: 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72  , and so the cur
b810: 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63  rent limit .** c
b820: 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79  an be queried by
b830: 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f   passing in a po
b840: 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74  inter to a negat
b850: 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69  ive number.  Thi
b860: 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  s.** file-contro
b870: 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  l is used intern
b880: 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  ally to implemen
b890: 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  t [PRAGMA mmap_s
b8a0: 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ize]..**.** <li>
b8b0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b8c0: 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  RACE]].** The [S
b8d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
b8e0: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
b8f0: 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72  provides advisor
b900: 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  y information.**
b910: 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75   to the VFS abou
b920: 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65  t what the highe
b930: 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20  r layers of the 
b940: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65  SQLite stack are
b950: 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20   doing..** This 
b960: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b970: 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53  used by some VFS
b980: 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e   activity tracin
b990: 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68  g [shims]..** Th
b9a0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
b9b0: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
b9c0: 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20  string.  Higher 
b9d0: 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a  layers in the.**
b9e0: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61   SQLite stack ma
b9f0: 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61  y generate insta
ba00: 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c  nces of this fil
ba10: 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20  e control if.** 
ba20: 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
ba30: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d  FCNTL_TRACE] com
ba40: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
ba50: 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
ba60: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ba70: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
ba80: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
ba90: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
baa0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
bab0: 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72  nterprets its ar
bac0: 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70  gument as a.** p
bad0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
bae0: 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74  eger and it writ
baf0: 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74  es a boolean int
bb00: 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64  o that integer d
bb10: 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77  epending.** on w
bb20: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
bb30: 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20  e file has been 
bb40: 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20  renamed, moved, 
bb50: 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65  or deleted since
bb60: 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74   it.** was first
bb70: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c   opened..**.** <
bb80: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bb90: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44  L_WIN32_GET_HAND
bba0: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  LE]].** The [SQL
bbb0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
bbc0: 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f  GET_HANDLE] opco
bbd0: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
bbe0: 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a 20  o obtain the.** 
bbf0: 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69 76  underlying nativ
bc00: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 73  e file handle as
bc10: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
bc20: 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54 68  file handle.  Th
bc30: 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72  is file.** contr
bc40: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
bc50: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 20  s argument as a 
bc60: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61 74  pointer to a nat
bc70: 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  ive file handle 
bc80: 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74 68  and.** writes th
bc90: 65 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c 75  e resulting valu
bca0: 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c  e there..**.** <
bcb0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bcc0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
bcd0: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  LE]].** The [SQL
bce0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
bcf0: 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f  SET_HANDLE] opco
bd00: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
bd10: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
bd20: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
bd30: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
bd40: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70  l method to swap
bd50: 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65   the file handle
bd60: 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a   with the one.**
bd70: 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
bd80: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
bd90: 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  .  This capabili
bda0: 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ty is used durin
bdb0: 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64  g testing.** and
bdc0: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
bdd0: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
bde0: 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20   SQLITE_TEST is 
bdf0: 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
be00: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
be10: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a  L_WAL_BLOCK]].**
be20: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
be30: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73  TL_WAL_BLOCK] is
be40: 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65   a signal to the
be50: 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20   VFS layer that 
be60: 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61  it might.** be a
be70: 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62  dvantageous to b
be80: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74  lock on the next
be90: 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65   WAL lock if the
bea0: 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d   lock is not imm
beb0: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69  ediately.** avai
bec0: 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20  lable.  The WAL 
bed0: 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73  subsystem issues
bee0: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72   this signal dur
bef0: 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63  ing rare.** circ
bf00: 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64  umstances in ord
bf10: 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62  er to fix a prob
bf20: 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74  lem with priorit
bf30: 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20  y inversion..** 
bf40: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
bf50: 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e  uld <em>not</em>
bf60: 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63   use this file-c
bf70: 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ontrol..**.** <l
bf80: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bf90: 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65  _ZIPVFS]].** The
bfa0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a   [SQLITE_FCNTL_Z
bfb0: 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73  IPVFS] opcode is
bfc0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
bfd0: 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c  zipvfs only. All
bfe0: 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68   other.** VFS sh
bff0: 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49  ould return SQLI
c000: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20  TE_NOTFOUND for 
c010: 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a  this opcode..**.
c020: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c030: 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54  FCNTL_RBU]].** T
c040: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c050: 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20  _RBU] opcode is 
c060: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74  implemented by t
c070: 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75  he special VFS u
c080: 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42  sed by.** the RB
c090: 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79  U extension only
c0a0: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53  .  All other VFS
c0b0: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53   should return S
c0c0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66  QLITE_NOTFOUND f
c0d0: 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64  or.** this opcod
c0e0: 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  e.  .** </ul>.*/
c0f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c100: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
c110: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
c120: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c130: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_GET_LOCKPRO
c140: 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23  XYFILE       2.#
c150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c160: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_SET_LOCKPROX
c170: 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64  YFILE       3.#d
c180: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c190: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TL_LAST_ERRNO   
c1a0: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
c1b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c1c0: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20  L_SIZE_HINT     
c1d0: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
c1e0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c1f0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
c200: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
c210: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c220: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
c230: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
c240: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
c250: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
c260: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
c270: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
c280: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20  N32_AV_RETRY    
c290: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
c2a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
c2b0: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20  SIST_WAL        
c2c0: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
c2d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
c2e0: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
c2f0: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51     11.#define SQ
c300: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
c310: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ME              
c320: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    12.#define SQL
c330: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
c340: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
c350: 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   13.#define SQLI
c360: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20  TE_FCNTL_PRAGMA 
c370: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c380: 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  14.#define SQLIT
c390: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
c3a0: 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31  LER            1
c3b0: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
c3c0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
c3d0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36  AME           16
c3e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c3f0: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20  FCNTL_MMAP_SIZE 
c400: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a               18.
c410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c420: 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20  CNTL_TRACE      
c430: 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23              19.#
c440: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c450: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20  NTL_HAS_MOVED   
c460: 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64             20.#d
c470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c480: 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20  TL_SYNC         
c490: 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65            21.#de
c4a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c4b0: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
c4c0: 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66  O        22.#def
c4d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c4e0: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
c4f0: 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69  E       23.#defi
c500: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c510: 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20  WAL_BLOCK       
c520: 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e         24.#defin
c530: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a  e SQLITE_FCNTL_Z
c540: 49 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20  IPVFS           
c550: 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65        25.#define
c560: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42   SQLITE_FCNTL_RB
c570: 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  U               
c580: 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20       26.#define 
c590: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
c5a0: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
c5b0: 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53      27.#define S
c5c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
c5d0: 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  NAL_POINTER     
c5e0: 20 20 20 32 38 0a 23 64 65 66 69 6e 65 20 53 51     28.#define SQ
c5f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c600: 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20  _GET_HANDLE     
c610: 20 20 32 39 0a 23 64 65 66 69 6e 65 20 53 51 4c    29.#define SQL
c620: 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20  ITE_FCNTL_PDB   
c630: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c640: 20 33 30 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74   30../* deprecat
c650: 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66  ed names */.#def
c660: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
c670: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
c680: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47    SQLITE_FCNTL_G
c690: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c6a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c6b0: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
c6c0: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
c6d0: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_SET_LOCKPROX
c6e0: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
c6f0: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  LITE_LAST_ERRNO 
c700: 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c 49              SQLI
c710: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52  TE_FCNTL_LAST_ER
c720: 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  RNO.../*.** CAPI
c730: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
c740: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
c750: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
c760: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
c770: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
c780: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
c790: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
c7a0: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
c7b0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
c7c0: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
c7d0: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
c7e0: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
c7f0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
c800: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
c810: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
c820: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
c830: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
c840: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
c850: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
c860: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
c870: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
c880: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
c890: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
c8a0: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
c8b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
c8c0: 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 54  able Extension T
c8d0: 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  hunk.**.** A poi
c8e0: 6e 74 65 72 20 74 6f 20 74 68 65 20 6f 70 61 71  nter to the opaq
c8f0: 75 65 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ue sqlite3_api_r
c900: 6f 75 74 69 6e 65 73 20 73 74 72 75 63 74 75 72  outines structur
c910: 65 20 69 73 20 70 61 73 73 65 64 20 61 73 0a 2a  e is passed as.*
c920: 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  * the third para
c930: 6d 65 74 65 72 20 74 6f 20 65 6e 74 72 79 20 70  meter to entry p
c940: 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62  oints of [loadab
c950: 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20  le extensions]. 
c960: 20 54 68 69 73 0a 2a 2a 20 73 74 72 75 63 74 75   This.** structu
c970: 72 65 20 6d 75 73 74 20 62 65 20 74 79 70 65 64  re must be typed
c980: 65 66 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  efed in order to
c990: 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d   work around com
c9a0: 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a  piler warnings.*
c9b0: 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f  * on some platfo
c9c0: 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  rms..*/.typedef 
c9d0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61  struct sqlite3_a
c9e0: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 71 6c 69  pi_routines sqli
c9f0: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
ca00: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
ca10: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
ca20: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
ca30: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
ca40: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
ca50: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
ca60: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
ca70: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
ca80: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
ca90: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
caa0: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
cab0: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
cac0: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
cad0: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
cae0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
caf0: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
cb00: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
cb10: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
cb20: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
cb30: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
cb40: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
cb50: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
cb60: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
cb70: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
cb80: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
cb90: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
cba0: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
cbb0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
cbc0: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
cbd0: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
cbe0: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
cbf0: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
cc00: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
cc10: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
cc20: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
cc30: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
cc40: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
cc50: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
cc60: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
cc70: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
cc80: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
cc90: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
cca0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
ccb0: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
ccc0: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
ccd0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
cce0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
ccf0: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
cd00: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
cd10: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
cd20: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
cd30: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
cd40: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
cd50: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
cd60: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
cd70: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
cd80: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
cd90: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
cda0: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
cdb0: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
cdc0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
cdd0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
cde0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
cdf0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
ce00: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
ce10: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
ce20: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
ce30: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
ce40: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
ce50: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
ce60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
ce70: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
ce80: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
ce90: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
cea0: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
ceb0: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
cec0: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
ced0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
cee0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
cef0: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
cf00: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
cf10: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
cf20: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
cf30: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
cf40: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
cf50: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
cf60: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
cf70: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
cf80: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
cf90: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
cfa0: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
cfb0: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
cfc0: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
cfd0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
cfe0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
cff0: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
d000: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
d010: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
d020: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
d030: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
d040: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
d050: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
d060: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
d070: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
d080: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
d090: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
d0a0: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
d0b0: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
d0c0: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
d0d0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
d0e0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
d0f0: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
d100: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
d110: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
d120: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
d130: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
d140: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
d150: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
d160: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
d170: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
d180: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
d190: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
d1a0: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
d1b0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
d1c0: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
d1d0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
d1e0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
d1f0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
d200: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
d210: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
d220: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
d230: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
d240: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
d250: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
d260: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
d270: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
d280: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
d290: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
d2a0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
d2b0: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
d2c0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
d2d0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
d2e0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
d2f0: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
d300: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
d310: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
d320: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
d330: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
d340: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
d350: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
d360: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
d370: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
d380: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
d390: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
d3a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
d3b0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
d3c0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
d3d0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
d3e0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
d3f0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
d400: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
d410: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
d420: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
d430: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
d440: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
d450: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
d460: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
d470: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
d480: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
d490: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
d4a0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
d4b0: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
d4c0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
d4d0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
d4e0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
d4f0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
d500: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
d510: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
d520: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
d530: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
d540: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
d550: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
d560: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
d570: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
d580: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
d590: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
d5a0: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
d5b0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
d5c0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d5d0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
d5e0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d5f0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
d600: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
d610: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
d620: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d630: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
d640: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d650: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
d660: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
d670: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
d680: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
d690: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d6a0: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
d6b0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d6c0: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
d6d0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
d6e0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
d6f0: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
d700: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
d710: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
d720: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
d730: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
d740: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
d750: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
d760: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
d770: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
d780: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
d790: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
d7a0: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
d7b0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
d7c0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
d7d0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
d7e0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
d7f0: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
d800: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
d810: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
d820: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
d830: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
d840: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
d850: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
d860: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
d870: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
d880: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
d890: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
d8a0: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
d8b0: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
d8c0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
d8d0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
d8e0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
d8f0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
d900: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
d910: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
d920: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
d930: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
d940: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
d950: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
d960: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
d970: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
d980: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
d990: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
d9a0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
d9b0: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
d9c0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
d9d0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
d9e0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
d9f0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
da00: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
da10: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
da20: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
da30: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
da40: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
da50: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
da60: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
da70: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
da80: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
da90: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
daa0: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
dab0: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
dac0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
dad0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
dae0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
daf0: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
db00: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
db10: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
db20: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
db30: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
db40: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
db50: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
db60: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
db70: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
db80: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
db90: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
dba0: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
dbb0: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
dbc0: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
dbd0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
dbe0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
dbf0: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
dc00: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
dc10: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
dc20: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
dc30: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
dc40: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
dc50: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
dc60: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
dc70: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
dc80: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
dc90: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
dca0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
dcb0: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
dcc0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
dcd0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
dce0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
dcf0: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
dd00: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
dd10: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
dd20: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
dd30: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
dd40: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
dd50: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
dd60: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
dd70: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
dd80: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
dd90: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
dda0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
ddb0: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
ddc0: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
ddd0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
dde0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
ddf0: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
de00: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
de10: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
de20: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
de30: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
de40: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
de50: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
de60: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
de70: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
de80: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
de90: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
dea0: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
deb0: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
dec0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
ded0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
dee0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
def0: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
df00: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
df10: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
df20: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
df30: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
df40: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
df50: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
df60: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
df70: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
df80: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
df90: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
dfa0: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
dfb0: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
dfc0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
dfd0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
dfe0: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
dff0: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
e000: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
e010: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
e020: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
e030: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
e040: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
e050: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
e060: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
e070: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
e080: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
e090: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
e0a0: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
e0b0: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
e0c0: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
e0d0: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
e0e0: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
e0f0: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
e100: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
e110: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
e120: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
e130: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
e140: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
e150: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
e160: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
e170: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
e180: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
e190: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
e1a0: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
e1b0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
e1c0: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
e1d0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
e1e0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
e1f0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
e200: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
e210: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
e220: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
e230: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
e240: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
e250: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
e260: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
e270: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
e280: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
e290: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
e2a0: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
e2b0: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
e2c0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
e2d0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
e2e0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
e2f0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
e300: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
e310: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
e320: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
e330: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
e340: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
e350: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
e360: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
e370: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
e380: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
e390: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
e3a0: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
e3b0: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
e3c0: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
e3d0: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
e3e0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
e3f0: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
e400: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
e410: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
e420: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
e430: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
e440: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
e450: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
e460: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
e470: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
e480: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
e490: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
e4a0: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
e4b0: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
e4c0: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
e4d0: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
e4e0: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
e4f0: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
e500: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
e510: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
e520: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
e530: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
e540: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
e550: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
e560: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
e570: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
e580: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
e590: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
e5a0: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
e5b0: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
e5c0: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
e5d0: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
e5e0: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
e5f0: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
e600: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
e610: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
e620: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
e630: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
e640: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
e650: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
e660: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
e670: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
e680: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
e690: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
e6a0: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
e6b0: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
e6c0: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
e6d0: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
e6e0: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
e6f0: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
e700: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
e710: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
e720: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
e730: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
e740: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
e750: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
e760: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
e770: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
e780: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
e790: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
e7a0: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
e7b0: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
e7c0: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
e7d0: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
e7e0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
e7f0: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
e800: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
e810: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
e820: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
e830: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
e840: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
e850: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
e860: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
e870: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
e880: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
e890: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
e8a0: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
e8b0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
e8c0: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
e8d0: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
e8e0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
e8f0: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
e900: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
e910: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
e920: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
e930: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
e940: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
e950: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
e960: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
e970: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
e980: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
e990: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
e9a0: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
e9b0: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
e9c0: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
e9d0: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
e9e0: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
e9f0: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
ea00: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
ea10: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
ea20: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
ea30: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
ea40: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
ea50: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
ea60: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
ea70: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
ea80: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
ea90: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
eaa0: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
eab0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
eac0: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
ead0: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
eae0: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
eaf0: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
eb00: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
eb10: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
eb20: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
eb30: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
eb40: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
eb50: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
eb60: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
eb70: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
eb80: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
eb90: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
eba0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ebb0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
ebc0: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
ebd0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
ebe0: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
ebf0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ec00: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
ec10: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
ec20: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
ec30: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
ec40: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
ec50: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
ec60: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
ec70: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
ec80: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
ec90: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
eca0: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
ecb0: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
ecc0: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
ecd0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
ece0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
ecf0: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
ed00: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
ed10: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
ed20: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
ed30: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
ed40: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
ed50: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
ed60: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
ed70: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
ed80: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
ed90: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
eda0: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
edb0: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
edc0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
edd0: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
ede0: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
edf0: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
ee00: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
ee10: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
ee20: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
ee30: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
ee40: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
ee50: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
ee60: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
ee70: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
ee80: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
ee90: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
eea0: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
eeb0: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
eec0: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
eed0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
eee0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
eef0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ef00: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
ef10: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
ef20: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
ef30: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
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 29 3b 0a 20 20  char *zName);.  
ef70: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
ef80: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
ef90: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
efa0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
efb0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
efc0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
efd0: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
efe0: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
eff0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
f000: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
f010: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
f020: 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ed in future ver
f030: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
f040: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
f050: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
f060: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
f070: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
f080: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f090: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
f0a0: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
f0b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
f0c0: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
f0d0: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
f0e0: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
f0f0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
f100: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
f110: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
f120: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
f130: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
f140: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
f150: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
f160: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
f170: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
f180: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
f190: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
f1a0: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
f1b0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
f1c0: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
f1d0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
f1e0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
f1f0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
f200: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
f210: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
f220: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
f230: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
f240: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
f250: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
f260: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
f270: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
f280: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
f290: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
f2a0: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
f2b0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
f2c0: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
f2d0: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
f2e0: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
f2f0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
f300: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
f310: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
f320: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
f330: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
f340: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
f350: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f360: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
f370: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
f380: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
f390: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
f3a0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
f3b0: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
f3c0: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
f3d0: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
f3e0: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
f3f0: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
f400: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
f410: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f420: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
f430: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
f440: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
f450: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
f460: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
f470: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
f480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f490: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
f4a0: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
f4b0: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
f4c0: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
f4d0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
f4e0: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
f4f0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
f500: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
f510: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
f520: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
f530: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
f540: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
f550: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
f560: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
f570: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
f580: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
f590: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
f5a0: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
f5b0: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
f5c0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
f5d0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
f5e0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
f5f0: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
f600: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
f610: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
f620: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
f630: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
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 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
f670: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
f680: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
f690: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
f6a0: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
f6b0: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
f6c0: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
f6d0: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
f6e0: 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f   given on the co
f6f0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
f700: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
f710: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
f720: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
f730: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
f740: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
f750: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
f760: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
f770: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
f780: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
f790: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
f7a0: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
f7b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
f7c0: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
f7d0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
f7e0: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
f7f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
f800: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
f810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f820: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
f830: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f840: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
f850: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
f860: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
f870: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
f880: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
f890: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
f8a0: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
f8b0: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
f8c0: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
f8d0: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
f8e0: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
f8f0: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
f900: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
f910: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
f920: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
f930: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
f940: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
f950: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
f960: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
f970: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
f980: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
f990: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f9a0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
f9b0: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
f9c0: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
f9d0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
f9e0: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
f9f0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
fa00: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
fa10: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
fa20: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
fa30: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
fa40: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
fa50: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
fa60: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
fa70: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
fa80: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
fa90: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
faa0: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
fab0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
fac0: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
fad0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
fae0: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
faf0: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
fb00: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
fb10: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
fb20: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
fb30: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
fb40: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
fb50: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
fb60: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fb70: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
fb80: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
fb90: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
fba0: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
fbb0: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
fbc0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fbd0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
fbe0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
fbf0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
fc00: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
fc10: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
fc20: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
fc30: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
fc40: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
fc50: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
fc60: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
fc70: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
fc80: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
fc90: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
fca0: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
fcb0: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
fcc0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
fcd0: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
fce0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
fcf0: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
fd00: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fd10: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
fd20: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
fd30: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
fd40: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
fd50: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
fd60: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
fd70: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
fd80: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
fd90: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
fda0: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
fdb0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fdc0: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
fdd0: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
fde0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
fdf0: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
fe00: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
fe10: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
fe20: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
fe30: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
fe40: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
fe50: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
fe60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
fe70: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
fe80: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
fe90: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
fea0: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
feb0: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
fec0: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
fed0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
fee0: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
fef0: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
ff00: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
ff10: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
ff20: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
ff30: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
ff40: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
ff50: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
ff60: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
ff70: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
ff80: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ff90: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
ffa0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
ffb0: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
ffc0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
ffd0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ffe0: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
fff0: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
10000 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
10010 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
10020 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
10030 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
10040 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
10050 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
10060 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
10070 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
10080 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
10090 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
100a0 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
100b0 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
100c0 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
100d0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
100e0 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
100f0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
10100 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
10110 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
10120 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10130 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
10140 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
10150 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
10160 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
10170 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
10180 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
10190 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
101a0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
101b0 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
101c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
101d0 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
101e0 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
101f0 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
10200 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
10210 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
10220 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
10230 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
10240 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
10250 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
10260 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
10270 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
10280 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
10290 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
102a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
102b0 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
102c0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
102d0 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
102e0 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
102f0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
10300 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
10310 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
10320 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
10330 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
10340 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
10350 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
10360 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
10370 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
10380 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
10390 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
103a0 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
103b0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
103c0 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
103d0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
103e0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
103f0 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
10400 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
10410 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
10420 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
10430 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
10440 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
10450 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
10460 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
10470 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
10480 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10490 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
104a0 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
104b0 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
104c0 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
104d0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
104e0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
104f0 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
10500 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
10510 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
10520 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
10530 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
10540 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
10550 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
10560 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
10570 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
10580 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
10590 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
105a0 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
105b0 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
105c0 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
105d0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
105e0 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
105f0 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
10600 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
10610 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
10620 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
10630 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
10640 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
10650 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
10660 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
10670 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
10680 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  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 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
106b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
106c0 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
106d0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
106e0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
106f0 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
10700 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
10710 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
10720 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10730 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
10740 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
10750 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
10760 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
10770 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
10780 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
10790 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
107a0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
107b0 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
107c0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
107d0 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
107e0 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
107f0 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
10800 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
10810 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
10820 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
10830 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
10840 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
10850 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
10860 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
10870 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
10880 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
10890 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
108a0 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
108b0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
108c0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
108d0 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
108e0 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
108f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
10900 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
10910 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
10920 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
10930 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
10940 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
10950 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
10960 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
10970 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
10980 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
10990 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
109a0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
109b0 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
109c0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
109d0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
109e0 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
109f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10a00 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
10a10 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
10a20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
10a30 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
10a40 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
10a50 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
10a60 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
10a70 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
10a80 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
10a90 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
10aa0 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
10ab0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
10ac0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
10ad0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
10ae0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
10af0 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
10b00 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
10b10 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
10b20 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
10b30 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
10b40 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
10b50 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
10b60 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
10b70 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  needs..**.** <b>
10b80 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
10b90 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
10ba0 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
10bb0 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  . The applicatio
10bc0 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
10bd0 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
10be0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
10bf0 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
10c00 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
10c10 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
10c20 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
10c30 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68  ng.</b>.**.** Th
10c40 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
10c50 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
10c60 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
10c70 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
10c80 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
10c90 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
10ca0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10cb0 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
10cc0 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
10cd0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
10ce0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
10cf0 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
10d00 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
10d10 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
10d20 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
10d30 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
10d40 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
10d50 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
10d60 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
10d70 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
10d80 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
10d90 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
10da0 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
10db0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
10dc0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
10dd0 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
10de0 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
10df0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
10e00 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
10e10 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
10e20 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67  teger.** [config
10e30 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20  uration option] 
10e40 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a  that determines.
10e50 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79  ** what property
10e60 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f   of SQLite is to
10e70 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20   be configured. 
10e80 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
10e90 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65  ments.** vary de
10ea0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b  pending on the [
10eb0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10ec0 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
10ed0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
10ee0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f  **.** ^When a co
10ef0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10f00 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
10f10 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
10f20 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
10f30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69  .** ^If the opti
10f40 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
10f50 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
10f60 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
10f70 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
10f80 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
10f90 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
10fa0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74  or code]..*/.int
10fb0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10fc0 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
10fd0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
10fe0 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
10ff0 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45  onnections.** ME
11000 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
11010 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
11020 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
11030 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
11040 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
11050 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
11060 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
11070 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
11080 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
11090 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
110a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
110b0 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
110c0 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
110d0 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
110e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
110f0 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
11100 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11110 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
11120 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
11130 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
11140 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
11150 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
11160 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
11170 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
11180 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
11190 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
111a0 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
111b0 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
111c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
111d0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
111e0 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
111f0 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
11200 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
11210 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
11220 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
11230 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
11240 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
11250 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
11260 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
11270 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
11280 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
11290 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ssful..*/.int sq
112a0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
112b0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
112c0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
112d0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
112e0 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
112f0 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
11300 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
11310 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
11320 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
11330 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
11340 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
11350 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
11360 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
11370 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
11380 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
11390 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
113a0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
113b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
113c0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
113d0 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
113e0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
113f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11400 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
11410 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
11420 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
11430 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
11440 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
11450 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
11460 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
11470 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
11480 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
11490 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
114a0 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
114b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
114c0 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
114d0 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
114e0 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
114f0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
11500 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
11510 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
11520 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
11530 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
11540 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
11550 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
11560 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
11570 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
11580 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
11590 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
115a0 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
115b0 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
115c0 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
115d0 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
115e0 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
115f0 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
11600 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
11610 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
11620 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
11630 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
11640 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
11650 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11660 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
11670 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
11680 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
11690 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
116a0 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
116b0 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
116c0 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
116d0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
116e0 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
116f0 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
11700 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
11710 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
11720 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
11730 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
11740 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
11750 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
11760 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
11770 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
11780 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
11790 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
117a0 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
117b0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
117c0 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
117d0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
117e0 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
117f0 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
11800 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
11810 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
11820 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
11830 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
11840 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
11850 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
11860 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
11870 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
11880 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
11890 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
118a0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
118b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
118c0 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
118d0 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
118e0 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
118f0 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
11900 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
11910 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
11920 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
11930 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
11940 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
11950 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
11960 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
11970 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
11980 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
11990 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
119a0 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
119b0 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
119c0 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
119d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
119e0 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
119f0 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
11a00 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
11a10 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
11a20 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
11a30 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
11a40 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
11a50 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
11a60 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
11a70 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
11a80 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
11a90 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
11aa0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
11ab0 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
11ac0 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
11ad0 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
11ae0 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
11af0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
11b00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11b10 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
11b20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
11b30 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
11b40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11b50 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  r.  For example,
11b60 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
11b70 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
11b80 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
11b90 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
11ba0 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
11bb0 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
11bc0 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
11bd0 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
11be0 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
11bf0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
11c00 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
11c10 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
11c20 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
11c30 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
11c40 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
11c50 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
11c60 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
11c70 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
11c80 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
11c90 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
11ca0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
11cb0 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
11cc0 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
11cd0 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
11ce0 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
11cf0 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
11d00 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
11d10 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
11d20 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
11d30 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
11d40 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11d50 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
11d60 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
11d70 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
11d80 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
11d90 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
11da0 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
11db0 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
11dc0 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
11dd0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
11de0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
11df0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
11e00 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11e10 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
11e20 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
11e30 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
11e40 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
11e50 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
11e60 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
11e70 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
11e80 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
11e90 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
11ea0 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
11eb0 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
11ec0 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
11ed0 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
11ee0 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
11ef0 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
11f00 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
11f10 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
11f20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
11f30 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
11f40 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
11f50 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
11f60 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
11f70 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
11f80 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11f90 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
11fa0 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
11fb0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11fc0 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
11fd0 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
11fe0 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
11ff0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
12000 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
12010 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
12020 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
12030 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
12040 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
12050 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
12060 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
12070 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
12080 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
12090 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
120a0 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
120b0 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
120c0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
120d0 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
120e0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
120f0 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
12100 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
12110 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
12120 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
12130 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
12140 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
12150 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
12160 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
12170 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
12180 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
12190 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
121a0 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
121b0 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
121c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
121d0 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
121e0 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
121f0 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
12200 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
12210 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
12220 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e  * KEYWORDS: {con
12230 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12240 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  n}.**.** These c
12250 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
12260 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
12270 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
12280 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
12290 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
122a0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
122b0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
122c0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
122d0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
122e0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
122f0 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
12300 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
12310 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
12320 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
12330 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12340 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
12350 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
12360 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
12370 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
12380 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
12390 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
123a0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
123b0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
123c0 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
123d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
123e0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
123f0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
12400 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
12410 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
12420 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
12430 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
12440 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
12450 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
12460 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  l>.** [[SQLITE_C
12470 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
12480 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
12490 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
124a0 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
124b0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
124c0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
124d0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
124e0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
124f0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12500 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
12510 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
12520 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
12530 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
12540 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
12550 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
12560 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
12570 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
12580 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
12590 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
125a0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
125b0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
125c0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
125d0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
125e0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
125f0 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
12600 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
12610 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
12620 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
12630 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
12640 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
12650 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
12660 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12670 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
12680 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
12690 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
126a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
126b0 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
126c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
126d0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
126e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
126f0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c  _MULTITHREAD]] <
12700 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12710 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
12720 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
12730 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
12740 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
12750 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
12760 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
12770 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
12780 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
12790 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
127a0 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
127b0 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
127c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
127d0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
127e0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
127f0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
12800 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
12810 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
12820 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
12830 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12840 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
12850 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
12860 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
12870 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
12880 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
12890 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
128a0 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
128b0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
128c0 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
128d0 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
128e0 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
128f0 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
12900 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12910 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
12920 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
12930 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12940 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
12950 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
12960 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12970 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
12980 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
12990 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
129a0 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
129b0 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
129c0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
129d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
129e0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
129f0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
12a00 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
12a10 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
12a20 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
12a30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12a40 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
12a50 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12a60 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c  G_SERIALIZED]] <
12a70 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12a80 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
12a90 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
12aa0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
12ab0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
12ac0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
12ad0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
12ae0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
12af0 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
12b00 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
12b10 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
12b20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
12b30 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
12b40 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
12b50 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
12b60 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
12b70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
12b80 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
12b90 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
12ba0 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
12bb0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
12bc0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12bd0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12be0 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
12bf0 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
12c00 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
12c10 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
12c20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12c30 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
12c40 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
12c50 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
12c60 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
12c70 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
12c80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12c90 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
12ca0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
12cb0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
12cc0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
12cd0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
12ce0 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
12cf0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
12d00 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
12d10 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
12d20 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
12d30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
12d40 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
12d50 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
12d60 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
12d70 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
12d80 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
12d90 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12da0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
12db0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
12dc0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
12dd0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
12de0 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
12df0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12e00 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
12e10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12e20 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
12e30 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
12e40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12e50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12e60 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
12e70 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
12e80 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
12e90 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
12ea0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
12eb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12ec0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12ed0 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
12ee0 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
12ef0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
12f00 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
12f10 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
12f20 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
12f30 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
12f40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12f50 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
12f60 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
12f70 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
12f80 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
12f90 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
12fa0 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
12fb0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12fc0 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
12fd0 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
12fe0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
12ff0 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
13000 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13010 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
13020 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13030 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
13040 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
13050 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13060 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  ETMALLOC option 
13070 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13080 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
13090 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
130a0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
130b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
130c0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
130d0 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ure..** The [sql
130e0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
130f0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
13100 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
13110 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
13120 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
13130 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
13140 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
13150 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
13160 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
13170 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
13180 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
13190 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
131a0 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
131b0 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
131c0 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
131d0 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
131e0 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
131f0 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
13200 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13210 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74  _MEMSTATUS]] <dt
13220 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
13230 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
13240 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
13250 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
13260 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  US option takes 
13270 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13280 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20  of type int,.** 
13290 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
132a0 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
132b0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
132c0 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
132d0 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20  on of.** memory 
132e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
132f0 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
13300 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13310 73 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a  statistics are.*
13320 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  * disabled, the 
13330 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
13340 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
13350 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
13360 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
13370 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
13380 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
13390 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
133a0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
133b0 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
133c0 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
133d0 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
133e0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
133f0 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a  3_status64()].**
13400 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
13410 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13420 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
13430 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
13440 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
13450 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
13460 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
13470 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
13480 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
13490 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
134a0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
134b0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
134c0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
134d0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
134e0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
134f0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13500 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
13510 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
13520 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
13530 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  TCH option speci
13540 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
13550 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74  mory buffer.** t
13560 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
13570 73 65 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d  se for scratch m
13580 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20  emory.  ^(There 
13590 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
135a0 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45  nts.** to SQLITE
135b0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a  _CONFIG_SCRATCH:
135c0 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38    A pointer an 8
135d0 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
135e0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66   memory buffer f
135f0 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63  rom which the sc
13600 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
13610 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61  s will be.** dra
13620 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  wn, the size of 
13630 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c  each scratch all
13640 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a  ocation (sz),.**
13650 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
13660 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74   number of scrat
13670 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28  ch allocations (
13680 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72  N).)^.** The fir
13690 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
136a0 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
136b0 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   an 8-byte align
136c0 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20  ed buffer.** of 
136d0 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
136e0 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
136f0 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
13700 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e  ot use more than
13710 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66   one scratch buf
13720 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e  fers per thread.
13730 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
13740 20 6e 65 76 65 72 20 72 65 71 75 65 73 74 20 61   never request a
13750 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
13760 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61  that is more tha
13770 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65  n 6.** times the
13780 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
13790 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ize..** ^If SQLi
137a0 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61  te needs needs a
137b0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72  dditional.** scr
137c0 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f  atch memory beyo
137d0 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
137e0 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66  ded by this conf
137f0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13800 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69  , then .** [sqli
13810 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69  te3_malloc()] wi
13820 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  ll be used to ob
13830 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  tain the memory 
13840 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57  needed.<p>.** ^W
13850 68 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74  hen the applicat
13860 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79  ion provides any
13870 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74   amount of scrat
13880 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a  ch memory using.
13890 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
138a0 5f 53 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65  _SCRATCH, SQLite
138b0 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73   avoids unnecess
138c0 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71  ary large.** [sq
138d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61  lite3_malloc|hea
138e0 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a  p allocations]..
138f0 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70  ** This can help
13900 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70   [Robson proof|p
13910 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c  revent memory al
13920 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
13930 73 5d 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a  s] due to heap.*
13940 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  * fragmentation 
13950 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d  in low-memory em
13960 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a  bedded systems..
13970 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
13980 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
13990 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53  AGECACHE]] <dt>S
139a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
139b0 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
139c0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
139d0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
139e0 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
139f0 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a  s a memory pool.
13a00 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  ** that SQLite c
13a10 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 64  an use for the d
13a20 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
13a30 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
13a40 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ult page.** cach
13a50 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13a60 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
13a70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13a80 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61   is a no-op if a
13a90 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
13aa0 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
13ab0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
13ac0 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
13ad0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
13ae0 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a  NFIG_PCACHE2]..*
13af0 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72  * ^There are thr
13b00 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
13b10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
13b20 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74  GECACHE: A point
13b30 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20  er to.** 8-byte 
13b40 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28  aligned memory (
13b50 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a 65 20  pMem), the size 
13b60 6f 66 20 65 61 63 68 20 70 61 67 65 20 63 61 63  of each page cac
13b70 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a  he line (sz),.**
13b80 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
13b90 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73 20 28  of cache lines (
13ba0 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
13bb0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
13bc0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
13bd0 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
13be0 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
13bf0 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
13c00 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29  n 512 and 65536)
13c10 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61   plus some extra
13c20 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a   bytes for each.
13c30 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
13c40 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
13c50 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64  extra bytes need
13c60 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68  ed by the page h
13c70 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20  eader.** can be 
13c80 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
13c90 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13ca0 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a  PCACHE_HDRSZ]..*
13cb0 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73  * ^It is harmles
13cc0 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
13cd0 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
13ce0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70  .** for the sz p
13cf0 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c  arameter to be l
13d00 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73  arger than neces
13d10 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a  sary.  The pMem.
13d20 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
13d30 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c   be either a NUL
13d40 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 20 70  L pointer or a p
13d50 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
13d60 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62  yte.** aligned b
13d70 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f  lock of memory o
13d80 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
13d90 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69 73 65  bytes, otherwise
13da0 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 62  .** subsequent b
13db0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
13dc0 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70  ined..** ^When p
13dd0 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  Mem is not NULL,
13de0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73 74 72   SQLite will str
13df0 69 76 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d  ive to use the m
13e00 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 0a 2a  emory provided.*
13e10 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70 61 67  * to satisfy pag
13e20 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c 20 66  e cache needs, f
13e30 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b  alling back to [
13e40 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13e50 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65 20 63  ] if.** a page c
13e60 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c 61 72  ache line is lar
13e70 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79 74 65  ger than sz byte
13e80 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20 74  s or if all of t
13e90 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a  he pMem buffer.*
13ea0 2a 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a  * is exhausted..
13eb0 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e  ** ^If pMem is N
13ec0 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e  ULL and N is non
13ed0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61 63 68  -zero, then each
13ee0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
13ef0 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20  tion.** does an 
13f00 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c  initial bulk all
13f10 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61 67 65  ocation for page
13f20 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a   cache memory.**
13f30 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
13f40 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69 63 69  alloc()] suffici
13f50 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68 65 20  ent for N cache 
13f60 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20 70 6f  lines if N is po
13f70 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20  sitive or.** of 
13f80 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20 69 66  -1024*N bytes if
13f90 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20   N is negative, 
13fa0 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c  . ^If additional
13fb0 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
13fc0 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
13fd0 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
13fe0 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 69  rovided by the i
13ff0 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61  nitial.** alloca
14000 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74  tion, then SQLit
14010 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
14020 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70  e3_malloc()] sep
14030 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61 63 68  arately for each
14040 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  .** additional c
14050 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e  ache line. </dd>
14060 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14070 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
14080 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14090 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
140a0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
140b0 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
140c0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
140d0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
140e0 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  r .** that SQLit
140f0 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61  e will use for a
14100 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
14110 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
14120 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79  ion needs.** bey
14130 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
14140 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ed for by [SQLIT
14150 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
14160 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
14170 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
14180 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  E]..** ^The SQLI
14190 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
141a0 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
141b0 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74  ailable if SQLit
141c0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  e is compiled.**
141d0 20 77 69 74 68 20 65 69 74 68 65 72 20 5b 53 51   with either [SQ
141e0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
141f0 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  YS3] or [SQLITE_
14200 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
14210 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  and returns.** [
14220 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
14230 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69   invoked otherwi
14240 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  se..** ^There ar
14250 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
14260 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
14270 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38  IG_HEAP:.** An 8
14280 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
14290 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
142a0 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
142b0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
142c0 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
142d0 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
142e0 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
142f0 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
14300 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
14310 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
14320 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
14330 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
14340 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
14350 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
14360 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
14370 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
14380 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
14390 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
143a0 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
143b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
143c0 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
143d0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
143e0 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  er is not NULL t
143f0 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
14400 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
14410 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
14420 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
14430 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
14440 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
14450 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
14460 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
14470 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
14480 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
14490 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
144a0 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
144b0 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
144c0 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
144d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
144e0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
144f0 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
14500 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
14510 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
14520 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
14530 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
14540 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
14550 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
14560 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14570 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
14580 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14590 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
145a0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
145b0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74  CONFIG_MUTEX opt
145c0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
145d0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
145e0 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  h is a.** pointe
145f0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
14600 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14610 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
14620 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
14630 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
14640 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65  fies alternative
14650 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
14660 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
14670 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65  used.** in place
14680 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
14690 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
146a0 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
146b0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
146c0 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
146d0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
146e0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
146f0 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
14700 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
14710 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
14720 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
14730 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
14740 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
14750 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14760 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
14770 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
14780 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
14790 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
147a0 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
147b0 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
147c0 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
147d0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
147e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
147f0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
14800 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
14810 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
14820 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
14830 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
14840 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
14850 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14860 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
14870 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
14880 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
14890 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
148a0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
148b0 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
148c0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
148d0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
148e0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
148f0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
14900 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
14910 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
14920 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
14930 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a  _mutex_methods].
14940 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
14950 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
14960 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
14970 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  d mutex routines
14980 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
14990 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
149a0 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
149b0 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c  efault mutex all
149c0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
149d0 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
149e0 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b  er used to track
149f0 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72   mutex usage for
14a00 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20   performance.** 
14a10 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73  profiling or tes
14a20 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c  ting, for exampl
14a30 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  e.   ^If SQLite 
14a40 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
14a50 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
14a60 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
14a70 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
14a80 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
14a90 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
14aa0 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
14ab0 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
14ac0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
14ad0 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
14ae0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
14af0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
14b00 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
14b10 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63  ONFIG_GETMUTEX c
14b20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14b30 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
14b40 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
14b50 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
14b60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14b70 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51  OKASIDE]] <dt>SQ
14b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
14b90 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
14ba0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14bb0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14bc0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
14bd0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
14be0 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68   determine.** th
14bf0 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f  e default size o
14c00 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  f lookaside memo
14c10 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61  ry on each [data
14c20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
14c30 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
14c40 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
14c50 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
14c60 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
14c70 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
14c80 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
14c90 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
14ca0 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
14cb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14cc0 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45  ion.)^  ^(SQLITE
14cd0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14ce0 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69  E.** sets the <i
14cf0 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
14d00 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
14d10 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
14d20 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
14d30 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74  option to [sqlit
14d40 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
14d50 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
14d60 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
14d70 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
14d80 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
14d90 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
14da0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
14db0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14dc0 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
14dd0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14de0 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
14df0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
14e00 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f  IG_PCACHE2 optio
14e10 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14e20 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
14e30 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  is .** a pointer
14e40 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
14e50 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
14e60 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
14e70 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 0a  bject specifies.
14e80 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ** the interface
14e90 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
14ea0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
14eb0 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51  tation.)^.** ^SQ
14ec0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
14ed0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
14ee0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14ef0 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a  2] object.</dd>.
14f00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14f10 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
14f20 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14f30 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c  NFIG_GETPCACHE2<
14f40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
14f50 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14f60 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 74 69  _GETPCACHE2 opti
14f70 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14f80 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
14f90 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
14fa0 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
14fb0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
14fc0 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
14fd0 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68   copies of.** th
14fe0 65 20 63 75 72 72 65 6e 74 20 70 61 67 65 20 63  e current page c
14ff0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
15000 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
15010 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
15020 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15030 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
15040 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
15050 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  /dt>.** <dd> The
15060 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
15070 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  OG option is use
15080 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74  d to configure t
15090 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f  he SQLite.** glo
150a0 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e  bal [error log].
150b0 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45  .** (^The SQLITE
150c0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
150d0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
150e0 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
150f0 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
15100 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
15110 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
15120 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
15130 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
15140 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
15150 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
15160 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
15170 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
15180 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
15190 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
151a0 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
151b0 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
151c0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
151d0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
151e0 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
151f0 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
15200 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
15210 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
15220 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
15230 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
15240 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
15250 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
15260 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
15270 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
15280 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
15290 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
152a0 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
152b0 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
152c0 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
152d0 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
152e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
152f0 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
15300 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
15310 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
15320 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
15330 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
15340 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
15350 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
15360 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
15370 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
15380 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
15390 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
153a0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
153b0 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
153c0 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
153d0 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
153e0 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
153f0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
15400 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
15410 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
15420 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
15430 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
15440 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
15450 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
15460 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
15470 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
15480 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
15490 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
154a0 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
154b0 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
154c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
154d0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
154e0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
154f0 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
15500 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15510 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
15520 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
15530 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  dd>^(The SQLITE_
15540 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f  CONFIG_URI optio
15550 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15560 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
15570 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e  e int..** If non
15580 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20  -zero, then URI 
15590 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
155a0 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66  ally enabled. If
155b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
155c0 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  s zero,.** then 
155d0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
155e0 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
155f0 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e  d.)^ ^If URI han
15600 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
15610 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c  y.** enabled, al
15620 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73  l filenames pass
15630 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ed to [sqlite3_o
15640 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
15650 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20  _open_v2()],.** 
15660 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
15670 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
15680 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
15690 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
156a0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
156b0 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
156c0 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
156d0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
156e0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
156f0 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
15700 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
15710 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
15720 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20  ened. ^If it is 
15730 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
15740 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
15750 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
15760 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
15770 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
15780 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
15790 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
157a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
157b0 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20  is opened. ^(By 
157c0 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
157d0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
157e0 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
157f0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
15800 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
15810 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
15820 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
15830 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
15840 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a   defined.)^.**.*
15850 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15860 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
15870 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49  _SCAN]] <dt>SQLI
15880 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
15890 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a  NG_INDEX_SCAN.**
158a0 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
158b0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
158c0 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69  _INDEX_SCAN opti
158d0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
158e0 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67  e integer.** arg
158f0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69  ument which is i
15900 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
15910 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72  boolean in order
15920 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
15930 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65  sable.** the use
15940 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
15950 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
15960 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65  ble scans in the
15970 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
15980 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
15990 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  t setting is det
159a0 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
159b0 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f  e [SQLITE_ALLOW_
159c0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
159d0 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CAN] compile-tim
159e0 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20  e option, or is 
159f0 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20  "on".** if that 
15a00 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
15a10 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ion is omitted..
15a20 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74  ** The ability t
15a30 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  o disable the us
15a40 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
15a50 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
15a60 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73  able scans.** is
15a70 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e   because some in
15a80 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20  correctly coded 
15a90 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69  legacy applicati
15aa0 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e  ons might malfun
15ab0 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68  ction.** when th
15ac0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69  e optimization i
15ad0 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76  s enabled.  Prov
15ae0 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74  iding the abilit
15af0 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20  y to.** disable 
15b00 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
15b10 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65   allows the olde
15b20 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61  r, buggy applica
15b30 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72  tion code to wor
15b40 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61  k.** without cha
15b50 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65  nge even with ne
15b60 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
15b70 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  SQLite..**.** [[
15b80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15b90 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
15ba0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15bb0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
15bc0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
15bd0 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
15be0 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
15bf0 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
15c00 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
15c10 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
15c20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
15c30 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
15c40 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
15c50 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
15c60 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
15c70 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  o-ops..** </dd>.
15c80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15c90 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a  ONFIG_SQLLOG]].*
15ca0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15cb0 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64  FIG_SQLLOG.** <d
15cc0 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  d>This option is
15cd0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
15ce0 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d  if sqlite is com
15cf0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
15d00 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
15d10 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f  _SQLLOG] pre-pro
15d20 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
15d30 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20  ined. The first 
15d40 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a  argument should.
15d50 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ** be a pointer 
15d60 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
15d70 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f   type void(*)(vo
15d80 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e  id*,sqlite3*,con
15d90 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a  st char*, int)..
15da0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68  ** The second sh
15db0 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20  ould be of type 
15dc0 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c  (void*). The cal
15dd0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
15de0 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a   by the library.
15df0 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61  ** in three sepa
15e00 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63  rate circumstanc
15e10 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62  es, identified b
15e20 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73  y the value pass
15e30 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  ed as the.** fou
15e40 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49  rth parameter. I
15e50 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
15e60 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65  ameter is 0, the
15e70 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
15e80 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73  onnection.** pas
15e90 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
15ea0 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a  d argument has j
15eb0 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  ust been opened.
15ec0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
15ed0 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ent.** points to
15ee0 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69   a buffer contai
15ef0 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66  ning the name of
15f00 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
15f10 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a  se file. If the.
15f20 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
15f30 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74  ter is 1, then t
15f40 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
15f50 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20   that the third 
15f60 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69  parameter.** poi
15f70 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20  nts to has just 
15f80 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f  been executed. O
15f90 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68  r, if the fourth
15fa0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c   parameter is 2,
15fb0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e   then.** the con
15fc0 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61  nection being pa
15fd0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
15fe0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
15ff0 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68  being closed. Th
16000 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
16010 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e  eter is passed N
16020 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65  ULL In this case
16030 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66  .  An example of
16040 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63   using this.** c
16050 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
16060 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20  ion can be seen 
16070 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c  in the "test_sql
16080 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69  log.c" source fi
16090 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e  le in.** the can
160a0 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f  onical SQLite so
160b0 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a  urce tree.</dd>.
160c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
160d0 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d  ONFIG_MMAP_SIZE]
160e0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
160f0 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
16100 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f  .** <dd>^SQLITE_
16110 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
16120 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69   takes two 64-bi
16130 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74  t integer (sqlit
16140 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73  e3_int64) values
16150 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65  .** that are the
16160 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69   default mmap si
16170 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65  ze limit (the de
16180 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f  fault setting fo
16190 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61  r.** [PRAGMA mma
161a0 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65  p_size]) and the
161b0 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
161c0 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
161d0 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
161e0 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65  t setting can be
161f0 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65   overridden by e
16200 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
16210 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  nection using.**
16220 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41   either the [PRA
16230 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63  GMA mmap_size] c
16240 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73  ommand, or by us
16250 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
16260 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
16270 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
16280 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d  .  ^(The maximum
16290 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
162a0 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69  ze.** will be si
162b0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
162c0 20 69 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f   if necessary so
162d0 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f   that it does no
162e0 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  t exceed the.** 
162f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78  compile-time max
16300 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73  imum mmap size s
16310 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
16320 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49  LITE_MAX_MMAP_SI
16330 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ZE] compile-time
16340 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49   option.)^.** ^I
16350 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e  f either argumen
16360 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  t to this option
16370 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
16380 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74  en that argument
16390 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74   is.** changed t
163a0 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69  o its compile-ti
163b0 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  me default..**.*
163c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
163d0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
163e0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
163f0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
16400 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54  APSIZE.** <dd>^T
16410 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16420 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
16430 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
16440 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69  vailable if SQLi
16450 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
16460 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69  d for Windows wi
16470 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57  th the [SQLITE_W
16480 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65  IN32_MALLOC] pre
16490 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
164a0 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51  .** defined. ^SQ
164b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
164c0 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73  2_HEAPSIZE takes
164d0 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e   a 32-bit unsign
164e0 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  ed integer value
164f0 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69  .** that specifi
16500 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73  es the maximum s
16510 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74  ize of the creat
16520 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b  ed heap..**.** [
16530 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
16540 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a  CACHE_HDRSZ]].**
16550 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16560 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a  IG_PCACHE_HDRSZ.
16570 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
16580 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16590 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61  _HDRSZ option ta
165a0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
165b0 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
165c0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
165d0 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77  an integer and w
165e0 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20  rites into that 
165f0 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62  integer the numb
16600 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62  er of extra.** b
16610 79 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65  ytes per page re
16620 71 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20  quired for each 
16630 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f  page in [SQLITE_
16640 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
16650 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74  ]..** The amount
16660 20 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20   of extra space 
16670 72 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61  required can cha
16680 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  nge depending on
16690 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a   the compiler,.*
166a0 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72  * target platfor
166b0 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65  m, and SQLite ve
166c0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  rsion..**.** [[S
166d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
166e0 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  SZ]].** <dt>SQLI
166f0 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a  TE_CONFIG_PMASZ.
16700 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
16710 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
16720 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
16730 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
16740 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75  which.** is an u
16750 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
16760 61 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d 69  and sets the "Mi
16770 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20  nimum PMA Size" 
16780 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72  for the multithr
16790 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20  eaded.** sorter 
167a0 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  to that integer.
167b0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69    The default mi
167c0 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69  nimum PMA Size i
167d0 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  s set by the.** 
167e0 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50  [SQLITE_SORTER_P
167f0 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  MASZ] compile-ti
16800 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20  me option.  New 
16810 74 68 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e  threads are laun
16820 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20  ched.** to help 
16830 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74  with sort operat
16840 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74  ions when multit
16850 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a  hreaded sorting.
16860 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75  ** is enabled (u
16870 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  sing the [PRAGMA
16880 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e   threads] comman
16890 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e  d) and the amoun
168a0 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20  t of content.** 
168b0 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78 63  to be sorted exc
168c0 65 65 64 73 20 74 68 65 20 70 61 67 65 20 73 69  eeds the page si
168d0 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e  ze times the min
168e0 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  imum of the.** [
168f0 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a  PRAGMA cache_siz
16900 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74  e] setting and t
16910 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  his value..**.**
16920 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16930 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d  _STMTJRNL_SPILL]
16940 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
16950 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
16960 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68  SPILL.** <dd>^Th
16970 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16980 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f  STMTJRNL_SPILL o
16990 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
169a0 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77  ngle parameter w
169b0 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20  hich.** becomes 
169c0 74 68 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a  the [statement j
169d0 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f  ournal] spill-to
169e0 2d 64 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e  -disk threshold.
169f0 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74    .** [Statement
16a00 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68   journals] are h
16a10 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e  eld in memory un
16a20 74 69 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28  til their size (
16a30 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63  in bytes).** exc
16a40 65 65 64 73 20 74 68 69 73 20 74 68 72 65 73 68  eeds this thresh
16a50 6f 6c 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f  old, at which po
16a60 69 6e 74 20 74 68 65 79 20 61 72 65 20 77 72 69  int they are wri
16a70 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a  tten to disk..**
16a80 20 4f 72 20 69 66 20 74 68 65 20 74 68 72 65 73   Or if the thres
16a90 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74  hold is -1, stat
16aa0 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61  ement journals a
16ab0 72 65 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a  re always held.*
16ac0 2a 20 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e  * exclusively in
16ad0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63   memory..** Sinc
16ae0 65 20 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74  e many statement
16af0 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20   journals never 
16b00 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65  become large, se
16b10 74 74 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a  tting the spill.
16b20 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20  ** threshold to 
16b30 61 20 76 61 6c 75 65 20 73 75 63 68 20 61 73 20  a value such as 
16b40 36 34 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c  64KiB can greatl
16b50 79 20 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f  y reduce the amo
16b60 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65  unt of.** I/O re
16b70 71 75 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72  quired to suppor
16b80 74 20 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c  t statement roll
16b90 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66  back..** The def
16ba0 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
16bb0 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 63  his setting is c
16bc0 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65  ontrolled by the
16bd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54  .** [SQLITE_STMT
16be0 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70  JRNL_SPILL] comp
16bf0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
16c00 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
16c10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16c20 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
16c30 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
16c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16c50 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
16c60 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
16c70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16c80 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
16c90 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
16ca0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16cb0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
16cc0 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
16cd0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
16ce0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16cf0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
16d00 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
16d10 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
16d20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16d30 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
16d40 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
16d50 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
16d60 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
16d70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
16d80 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
16d90 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
16da0 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
16db0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
16dc0 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
16dd0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
16de0 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
16df0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16e00 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
16e10 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
16e20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16e30 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
16e40 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
16e50 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
16e60 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
16e70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16e80 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
16e90 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
16ea0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
16eb0 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
16ec0 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
16ed0 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
16ee0 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
16ef0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16f00 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
16f10 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
16f20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16f30 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16f40 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f         14  /* no
16f50 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
16f60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16f70 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
16f80 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
16f90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16fa0 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
16fb0 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
16fc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16fd0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20  TE_CONFIG_URI   
16fe0 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e         17  /* in
16ff0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
17000 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17010 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73  E2      18  /* s
17020 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
17030 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
17040 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17050 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39  _GETPCACHE2   19
17060 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
17070 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
17080 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17090 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
170a0 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f  INDEX_SCAN 20  /
170b0 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
170c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
170d0 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20  QLLOG       21  
170e0 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64  /* xSqllog, void
170f0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
17100 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
17110 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73  SIZE    22  /* s
17120 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71  qlite3_int64, sq
17130 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23  lite3_int64 */.#
17140 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17150 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
17160 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20  IZE      23  /* 
17170 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65  int nByte */.#de
17180 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17190 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
171a0 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e         24  /* in
171b0 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e  t *psz */.#defin
171c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
171d0 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20  PMASZ           
171e0 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67      25  /* unsig
171f0 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f  ned int szPma */
17200 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17210 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
17220 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f  SPILL      26  /
17230 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a  * int nByte */..
17240 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17250 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
17260 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
17270 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
17280 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
17290 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
172a0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
172b0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
172c0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
172d0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
172e0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
172f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
17300 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
17310 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
17320 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
17330 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
17340 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
17350 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
17360 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
17370 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17380 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
17390 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
173a0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
173b0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
173c0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
173d0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
173e0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
173f0 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
17400 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
17410 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
17420 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
17430 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
17440 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
17450 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
17460 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
17470 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
17480 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
17490 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
174a0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
174b0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
174c0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
174d0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
174e0 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
174f0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
17500 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
17510 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
17520 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
17530 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
17540 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
17550 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17560 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
17570 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
17580 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
17590 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
175a0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
175b0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
175c0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
175d0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
175e0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
175f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
17600 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
17610 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
17620 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
17630 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
17640 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
17650 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
17660 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
17670 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
17680 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
17690 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
176a0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
176b0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
176c0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
176d0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
176e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
176f0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
17700 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
17710 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
17720 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
17730 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
17740 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
17750 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
17760 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
17770 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
17780 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
17790 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
177a0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
177b0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
177c0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
177d0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
177e0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
177f0 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
17800 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
17810 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
17820 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
17830 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
17840 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
17850 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
17860 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
17870 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
17880 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17890 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
178a0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
178b0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
178c0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
178d0 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
178e0 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
178f0 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
17900 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
17910 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
17920 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
17930 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
17940 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
17950 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
17960 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
17970 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
17980 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
17990 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
179a0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
179b0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
179c0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
179d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
179e0 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
179f0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
17a00 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
17a10 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
17a20 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
17a30 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
17a40 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
17a50 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
17a60 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
17a70 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
17a80 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
17a90 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
17aa0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
17ab0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
17ac0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
17ad0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
17ae0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
17af0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
17b00 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
17b10 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
17b20 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
17b30 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
17b40 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
17b50 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
17b60 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
17b70 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
17b80 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
17b90 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
17ba0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
17bb0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
17bc0 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
17bd0 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
17be0 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
17bf0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
17c00 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17c10 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
17c20 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
17c30 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
17c40 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
17c50 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
17c60 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
17c70 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
17c80 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
17c90 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
17ca0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
17cb0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
17cc0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
17cd0 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
17ce0 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
17cf0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
17d00 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
17d10 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
17d20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
17d30 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
17d40 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
17d50 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
17d60 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
17d70 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
17d80 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
17d90 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
17da0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
17db0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17dc0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
17dd0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
17de0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
17df0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
17e00 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
17e10 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
17e20 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
17e30 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
17e40 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
17e50 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17e60 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
17e70 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
17e80 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
17e90 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
17ea0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
17eb0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
17ec0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
17ed0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33  NFIG_ENABLE_FTS3
17ee0 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a  _TOKENIZER</dt>.
17ef0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
17f00 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
17f10 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
17f20 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65  e the two-argume
17f30 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  nt.** version of
17f40 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e   the [fts3_token
17f50 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e  izer()] function
17f60 20 77 68 69 63 68 20 69 73 20 70 61 72 74 20 6f   which is part o
17f70 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20  f the.** [FTS3] 
17f80 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68  full-text search
17f90 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f   engine extensio
17fa0 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  n..** There shou
17fb0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
17fc0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
17fd0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
17fe0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
17ff0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
18000 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74  o disable fts3_t
18010 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a  okenizer() or.**
18020 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
18030 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  ble fts3_tokeniz
18040 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65  er() or negative
18050 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
18060 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67  tting.** unchang
18070 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
18080 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18090 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
180a0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
180b0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
180c0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
180d0 74 65 20 77 68 65 74 68 65 72 20 66 74 73 33 5f  te whether fts3_
180e0 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73  tokenizer is dis
180f0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
18100 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
18110 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
18120 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
18130 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
18140 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
18150 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73  h case the new s
18160 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
18170 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
18180 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18190 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
181a0 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49  BLE_LOAD_EXTENSI
181b0 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ON</dt>.** <dd> 
181c0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
181d0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
181e0 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73  r disable the [s
181f0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
18200 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65  nsion()].** inte
18210 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e  rface independen
18220 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64  tly of the [load
18230 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51  _extension()] SQ
18240 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  L function..** T
18250 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  he [sqlite3_enab
18260 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
18270 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73  n()] API enables
18280 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74   or disables bot
18290 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b  h the.** C-API [
182a0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
182b0 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68  ension()] and th
182c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b  e SQL function [
182d0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
182e0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
182f0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
18300 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
18310 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72 73  ** When the firs
18320 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
18330 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
18340 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65  1, then only the
18350 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61   C-API is.** ena
18360 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  bled and the SQL
18370 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e   function remain
18380 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20  s disabled.  If 
18390 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
183a0 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e  nt to.** this in
183b0 74 65 72 66 61 63 65 20 69 73 20 30 2c 20 74 68  terface is 0, th
183c0 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50  en both the C-AP
183d0 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  I and the SQL fu
183e0 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62  nction are disab
183f0 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  led..** If the f
18400 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
18410 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61   -1, then no cha
18420 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f  nges are made to
18430 20 73 74 61 74 65 20 6f 66 20 65 69 74 68 65 72   state of either
18440 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72   the.** C-API or
18450 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
18460 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  n..** The second
18470 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
18480 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
18490 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
184a0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
184b0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
184c0 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74  e whether [sqlit
184d0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
184e0 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  n()] interface.*
184f0 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72  * is disabled or
18500 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69   enabled followi
18510 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
18520 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18530 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20  ter may.** be a 
18540 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
18550 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
18560 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e  new setting is n
18570 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
18580 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
18590 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
185a0 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c  NFIG_MAINDBNAME<
185b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
185c0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
185d0 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
185e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69  name of the "mai
185f0 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73  n" database.** s
18600 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c  chema.  ^The sol
18610 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
18620 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e  pointer to a con
18630 73 74 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e  stant UTF8 strin
18640 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  g.** which will 
18650 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73  become the new s
18660 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c  chema name in pl
18670 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20  ace of "main".  
18680 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20  ^SQLite.** does 
18690 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  not make a copy 
186a0 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20  of the new main 
186b0 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69  schema name stri
186c0 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69  ng, so the appli
186d0 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
186e0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
186f0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
18700 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49  nto this DBCONFI
18710 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68  G option is unch
18720 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61  anged.** until a
18730 66 74 65 72 20 74 68 65 20 64 61 74 61 62 61 73  fter the databas
18740 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
18750 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ses..** </dd>.**
18760 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
18770 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
18780 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a  ON_CLOSE</dt>.**
18790 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77   <dd> Usually, w
187a0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69  hen a database i
187b0 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c  n wal mode is cl
187c0 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64  osed or detached
187d0 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61   from a .** data
187e0 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c  base handle, SQL
187f0 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68  ite checks if th
18800 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61  is will mean tha
18810 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20  t there are now 
18820 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  no .** connectio
18830 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65  ns at all to the
18840 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f   database. If so
18850 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20  , it performs a 
18860 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f  checkpoint .** o
18870 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20  peration before 
18880 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e  closing the conn
18890 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74  ection. This opt
188a0 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20  ion may be used 
188b0 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74  to.** override t
188c0 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54  his behaviour. T
188d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
188e0 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  er passed to thi
188f0 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  s operation.** i
18900 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e  s an integer - n
18910 6f 6e 2d 7a 65 72 6f 20 74 6f 20 64 69 73 61 62  on-zero to disab
18920 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f  le checkpoints-o
18930 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f  n-close, or zero
18940 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74   (the.** default
18950 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d  ) to enable them
18960 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
18970 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
18980 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
18990 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20  r.** into which 
189a0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
189b0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
189c0 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74  ether checkpoint
189d0 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61  s-on-close.** ha
189e0 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64  ve been disabled
189f0 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65   - 0 if they are
18a00 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31   not disabled, 1
18a10 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a   if they are..**
18a20 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
18a30 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
18a40 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41  LITE_DBCONFIG_MA
18a50 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20  INDBNAME        
18a60 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73      1000 /* cons
18a70 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69  t char* */.#defi
18a80 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18a90 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
18aa0 20 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a           1001 /*
18ab0 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
18ac0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18ad0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
18ae0 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20  _FKEY           
18af0 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1002 /* int int*
18b00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18b10 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18b20 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  LE_TRIGGER      
18b30 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e    1003 /* int in
18b40 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
18b50 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18b60 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49  ABLE_FTS3_TOKENI
18b70 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20  ZER 1004 /* int 
18b80 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
18b90 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18ba0 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45  ENABLE_LOAD_EXTE
18bb0 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e  NSION 1005 /* in
18bc0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
18bd0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
18be0 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f  G_NO_CKPT_ON_CLO
18bf0 53 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20  SE      1006 /* 
18c00 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
18c10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
18c20 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
18c30 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
18c40 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Codes.** METHOD:
18c50 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
18c60 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
18c70 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
18c80 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
18c90 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
18ca0 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
18cb0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
18cc0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
18cd0 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
18ce0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
18cf0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
18d00 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
18d10 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
18d20 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
18d30 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
18d40 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
18d50 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
18d60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18d70 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
18d80 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  wid.** METHOD: s
18d90 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61  qlite3.**.** ^Ea
18da0 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
18db0 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
18dc0 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
18dd0 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
18de0 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
18df0 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
18e00 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
18e10 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
18e20 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
18e30 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
18e40 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
18e50 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
18e60 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
18e70 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
18e80 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
18e90 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
18ea0 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
18eb0 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
18ec0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
18ed0 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
18ee0 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
18ef0 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
18f00 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
18f10 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
18f20 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
18f30 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
18f40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
18f50 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
18f60 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
18f70 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
18f80 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a  rowid] of the .*
18f90 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  * most recent su
18fa0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
18fb0 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
18fc0 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
18fd0 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
18fe0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18ff0 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73  n D..** ^Inserts
19000 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
19010 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
19020 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a   not recorded..*
19030 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
19040 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
19050 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a  to rowid tables.
19060 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
19070 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74  urred on the dat
19080 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19090 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c   D, .** then sql
190a0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
190b0 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e  _rowid(D) return
190c0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s zero..**.** ^(
190d0 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
190e0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
190f0 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
19100 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
19110 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
19120 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
19130 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
19140 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
19150 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
19160 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
19170 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
19180 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
19190 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
191a0 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
191b0 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
191c0 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
191d0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
191e0 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
191f0 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
19200 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
19210 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
19220 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
19230 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
19240 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
19250 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
19260 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
19270 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
19280 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
19290 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
192a0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
192b0 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
192c0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
192d0 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
192e0 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
192f0 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
19300 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
19310 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
19320 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
19330 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
19340 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
19350 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
19360 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
19370 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
19380 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
19390 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
193a0 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
193b0 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
193c0 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
193d0 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
193e0 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
193f0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
19400 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
19410 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
19420 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
19430 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
19440 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
19450 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
19460 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
19470 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
19480 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
19490 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
194a0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
194b0 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
194c0 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
194d0 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
194e0 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
194f0 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
19500 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
19510 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
19520 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
19530 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
19540 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
19550 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
19560 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
19570 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
19580 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
19590 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
195a0 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
195b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
195c0 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
195d0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
195e0 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
195f0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
19600 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
19610 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
19620 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
19630 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
19640 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
19650 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19660 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
19670 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
19680 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
19690 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
196a0 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
196b0 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
196c0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
196d0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
196e0 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
196f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
19700 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
19710 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
19720 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44  dified.** METHOD
19730 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
19740 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
19750 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
19760 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
19770 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a  ed, inserted or.
19780 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  ** deleted by th
19790 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
197a0 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
197b0 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
197c0 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
197d0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
197e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69  connection speci
197f0 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79  fied by the only
19800 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
19810 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
19820 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
19830 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
19840 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61  ot modify the va
19850 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
19860 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
19870 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68  ..**.** ^Only ch
19880 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63  anges made direc
19890 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52  tly by the INSER
198a0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
198b0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
198c0 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
198d0 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e  - auxiliary chan
198e0 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43  ges caused by [C
198f0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
19900 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b  triggers], .** [
19910 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
19920 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45  ons] or [REPLACE
19930 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
19940 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20  olution are not 
19950 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  counted..** .** 
19960 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
19970 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
19980 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49  cepted by .** [I
19990 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
199a0 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74  r | INSTEAD OF t
199b0 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74  riggers] are not
199c0 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76   counted. ^The v
199d0 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65  alue .** returne
199e0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
199f0 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65  nges() immediate
19a00 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45  ly after an INSE
19a10 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a  RT, UPDATE or .*
19a20 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  * DELETE stateme
19a30 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77  nt run on a view
19a40 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e   is always zero.
19a50 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61   Only changes ma
19a60 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74  de to real .** t
19a70 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65  ables are counte
19a80 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20  d..**.** Things 
19a90 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63  are more complic
19aa0 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69  ated if the sqli
19ab0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
19ac0 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65  nction is.** exe
19ad0 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72  cuted while a tr
19ae0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73  igger program is
19af0 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d   running. This m
19b00 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65  ay happen if the
19b10 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
19b20 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
19b30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f  SQL function], o
19b40 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20  r if some other 
19b50 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
19b60 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c  tion invokes sql
19b70 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64  ite3_changes() d
19b80 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69  irectly. Essenti
19b90 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c  ally:.** .** <ul
19ba0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65  >.**   <li> ^(Be
19bb0 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20  fore entering a 
19bc0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
19bd0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
19be0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
19bf0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
19c00 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61  ) function is sa
19c10 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74  ved. After the t
19c20 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a  rigger program .
19c30 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69  **        has fi
19c40 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67  nished, the orig
19c50 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65  inal value is re
19c60 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a  stored.)^.** .**
19c70 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e     <li> ^(Within
19c80 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
19c90 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20  am each INSERT, 
19ca0 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54  UPDATE and DELET
19cb0 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61  E .**        sta
19cc0 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20  tement sets the 
19cd0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
19ce0 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
19cf0 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75  s() .**        u
19d00 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61  pon completion a
19d10 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75  s normal. Of cou
19d20 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20  rse, this value 
19d30 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65  will not include
19d40 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20   .**        any 
19d50 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65  changes performe
19d60 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72  d by sub-trigger
19d70 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65  s, as the sqlite
19d80 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
19d90 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c         value wil
19da0 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72  l be saved and r
19db0 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61  estored after ea
19dc0 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68  ch sub-trigger h
19dd0 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75  as run.)^.** </u
19de0 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20  l>.** .** ^This 
19df0 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68  means that if th
19e00 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  e changes() SQL 
19e10 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d  function (or sim
19e20 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a  ilar) is used.**
19e30 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e   by the first IN
19e40 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
19e50 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
19e60 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
19e70 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e  r, it .** return
19e80 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73  s the value as s
19e90 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c  et when the call
19ea0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65  ing statement be
19eb0 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  gan executing..*
19ec0 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64  * ^If it is used
19ed0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f   by the second o
19ee0 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63  r subsequent suc
19ef0 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  h statement with
19f00 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a  in a trigger .**
19f10 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61   program, the va
19f20 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66  lue returned ref
19f30 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72  lects the number
19f40 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
19f50 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65  d by the .** pre
19f60 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50  vious INSERT, UP
19f70 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
19f80 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
19f90 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
19fa0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
19fb0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
19fc0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
19fd0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
19fe0 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
19ff0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
1a000 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
1a010 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
1a020 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1a030 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
1a040 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
1a050 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a060 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
1a070 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
1a080 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
1a090 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1a0a0 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
1a0b0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
1a0c0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
1a0d0 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
1a0e0 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
1a0f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1a100 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
1a110 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
1a120 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1a130 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1a140 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1a150 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
1a160 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20   rows inserted, 
1a170 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64  modified or.** d
1a180 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49  eleted by all [I
1a190 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
1a1a0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
1a1b0 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65  tements complete
1a1c0 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64  d.** since the d
1a1d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a1e0 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69  on was opened, i
1a1f0 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65  ncluding those e
1a200 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61  xecuted as.** pa
1a210 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72  rt of trigger pr
1a220 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69  ograms. ^Executi
1a230 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
1a240 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
1a250 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61  nt.** does not a
1a260 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20  ffect the value 
1a270 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1a280 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1a290 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61  s()..** .** ^Cha
1a2a0 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72  nges made as par
1a2b0 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65  t of [foreign ke
1a2c0 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69  y actions] are i
1a2d0 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a  ncluded in the.*
1a2e0 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f  * count, but tho
1a2f0 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  se made as part 
1a300 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74  of REPLACE const
1a310 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
1a320 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68   are.** not. ^Ch
1a330 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
1a340 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
1a350 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20  pted by INSTEAD 
1a360 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20  OF triggers .** 
1a370 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1a380 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  .** .** See also
1a390 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
1a3a0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
1a3b0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
1a3c0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
1a3d0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
1a3e0 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
1a3f0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
1a400 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1a410 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
1a420 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
1a430 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a440 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
1a450 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1a460 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
1a470 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
1a480 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
1a490 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1a4a0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
1a4b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1a4c0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
1a4d0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1a4e0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
1a4f0 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
1a500 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54  ing Query.** MET
1a510 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1a520 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1a530 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
1a540 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
1a550 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
1a560 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
1a570 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
1a580 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
1a590 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
1a5a0 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
1a5b0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
1a5c0 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
1a5d0 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
1a5e0 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
1a5f0 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
1a600 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
1a610 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
1a620 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
1a630 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
1a640 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
1a650 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
1a660 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
1a670 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
1a680 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
1a690 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
1a6a0 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
1a6b0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
1a6c0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
1a6d0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
1a6e0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
1a6f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a700 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
1a710 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
1a720 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
1a730 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1a740 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1a750 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
1a760 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
1a770 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
1a780 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
1a790 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1a7a0 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
1a7b0 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
1a7c0 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
1a7d0 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
1a7e0 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
1a7f0 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
1a800 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
1a810 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
1a820 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
1a830 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
1a840 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
1a850 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
1a860 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
1a870 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
1a880 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
1a890 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
1a8a0 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
1a8b0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
1a8c0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
1a8d0 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
1a8e0 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
1a8f0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
1a900 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
1a910 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
1a920 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
1a930 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
1a940 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
1a950 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1a960 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
1a970 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a980 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
1a990 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
1a9a0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1a9b0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1a9c0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1a9d0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1a9e0 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
1a9f0 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
1aa00 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
1aa10 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
1aa20 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
1aa30 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
1aa40 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
1aa50 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1aa60 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
1aa70 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1aa80 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1aa90 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
1aaa0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
1aab0 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
1aac0 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
1aad0 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
1aae0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
1aaf0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
1ab00 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1ab10 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
1ab20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
1ab30 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
1ab40 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
1ab50 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
1ab60 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
1ab70 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1ab80 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1ab90 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
1aba0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1abb0 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
1abc0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1abd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
1abe0 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
1abf0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
1ac00 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
1ac10 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
1ac20 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
1ac30 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1ac40 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
1ac50 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1ac60 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
1ac70 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
1ac80 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
1ac90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1aca0 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
1acb0 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
1acc0 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
1acd0 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
1ace0 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
1acf0 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
1ad00 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
1ad10 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1ad20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
1ad30 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
1ad40 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
1ad50 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
1ad60 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
1ad70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
1ad80 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1ad90 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
1ada0 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
1adb0 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
1adc0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
1add0 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
1ade0 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
1adf0 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
1ae00 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
1ae10 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
1ae20 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
1ae30 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
1ae40 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
1ae50 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
1ae60 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
1ae70 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
1ae80 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
1ae90 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
1aea0 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
1aeb0 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
1aec0 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
1aed0 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
1aee0 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
1aef0 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
1af00 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
1af10 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
1af20 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
1af30 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
1af40 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
1af50 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
1af60 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
1af70 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
1af80 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
1af90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
1afa0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1afb0 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
1afc0 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
1afd0 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
1afe0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
1aff0 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
1b000 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
1b010 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
1b020 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
1b030 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
1b040 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
1b050 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
1b060 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
1b070 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
1b080 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
1b090 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
1b0a0 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
1b0b0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
1b0c0 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
1b0d0 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
1b0e0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1b0f0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
1b100 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
1b110 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
1b120 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
1b130 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
1b140 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
1b150 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
1b160 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
1b170 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
1b180 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1b190 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
1b1a0 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
1b1b0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1b1c0 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
1b1d0 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
1b1e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
1b1f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
1b200 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
1b210 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1b220 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
1b230 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
1b240 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
1b250 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
1b260 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1b270 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
1b280 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
1b290 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
1b2a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
1b2b0 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
1b2c0 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
1b2d0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1b2e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
1b2f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b300 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
1b310 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
1b320 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
1b330 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ors.** KEYWORDS:
1b340 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63   {busy-handler c
1b350 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68  allback} {busy h
1b360 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  andler}.** METHO
1b370 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1b380 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75   ^The sqlite3_bu
1b390 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50  sy_handler(D,X,P
1b3a0 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  ) routine sets a
1b3b0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1b3c0 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67  on X.** that mig
1b3d0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
1b3e0 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
1b3f0 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
1b400 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
1b410 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73  access a databas
1b420 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74  e table associat
1b430 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61  ed with.** [data
1b440 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1b450 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20   D when another 
1b460 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
1b470 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62  cess has the tab
1b480 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68  le locked..** Th
1b490 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
1b4a0 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61  andler() interfa
1b4b0 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d  ce is used to im
1b4c0 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69  plement.** [sqli
1b4d0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1b4e0 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  ()] and [PRAGMA 
1b4f0 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a  busy_timeout]..*
1b500 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
1b510 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1b520 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
1b530 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74  _BUSY].** is ret
1b540 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
1b550 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
1b560 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
1b570 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1b580 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
1b590 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
1b5a0 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
1b5b0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
1b5c0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
1b5d0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
1b5e0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
1b5f0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
1b600 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
1b610 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
1b620 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
1b630 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1b640 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1b650 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
1b660 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
1b670 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1b680 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1b690 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
1b6a0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
1b6b0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
1b6c0 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f  n invoked previo
1b6d0 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d  usly for the sam
1b6e0 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  e locking event.
1b6f0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
1b700 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
1b710 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
1b720 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
1b730 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
1b740 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1b750 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
1b760 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e  _BUSY] is return
1b770 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  ed.** to the app
1b780 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  lication..** ^If
1b790 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1b7a0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1b7b0 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
1b7c0 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
1b7d0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
1b7e0 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63  tabase and the c
1b7f0 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
1b800 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
1b810 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
1b820 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
1b830 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
1b840 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
1b850 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
1b860 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
1b870 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
1b880 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
1b890 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
1b8a0 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
1b8b0 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
1b8c0 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
1b8d0 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
1b8e0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1b8f0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1b900 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ion instead of i
1b910 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20  nvoking the .** 
1b920 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1b930 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
1b940 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
1b950 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1b960 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
1b970 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
1b980 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
1b990 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1b9a0 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
1b9b0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1b9c0 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
1b9d0 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
1b9e0 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
1b9f0 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
1ba00 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
1ba10 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
1ba20 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
1ba30 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1ba40 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
1ba50 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
1ba60 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
1ba70 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
1ba80 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1ba90 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
1baa0 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
1bab0 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
1bac0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
1bad0 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
1bae0 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
1baf0 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
1bb00 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
1bb10 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
1bb20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1bb30 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
1bb40 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
1bb50 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
1bb60 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
1bb70 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
1bb80 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
1bb90 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
1bba0 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
1bbb0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
1bbc0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1bbd0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  LL..**.** ^(Ther
1bbe0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1bbf0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1bc00 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
1bc10 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
1bc20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
1bc30 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
1bc40 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
1bc50 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
1bc60 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
1bc70 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
1bc80 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1bc90 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
1bca0 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67  ** or evaluating
1bcb0 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1bcc0 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68  meout=N] will ch
1bcd0 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79  ange the.** busy
1bce0 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75   handler and thu
1bcf0 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76  s clear any prev
1bd00 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20  iously set busy 
1bd10 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
1bd20 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1bd30 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
1bd40 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
1bd50 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
1bd60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1bd70 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1bd80 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1bd90 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  er.  In other wo
1bda0 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79  rds,.** the busy
1bdb0 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20   handler is not 
1bdc0 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20  reentrant.  Any 
1bdd0 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
1bde0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
1bdf0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
1be00 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
1be10 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
1be20 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1be30 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
1be40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1be50 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
1be60 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1be70 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
1be80 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1be90 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29  (sqlite3*,int(*)
1bea0 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64  (void*,int),void
1beb0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1bec0 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
1bed0 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f  Timeout.** METHO
1bee0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1bef0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
1bf00 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
1bf10 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
1bf20 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
1bf30 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
1bf40 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
1bf50 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
1bf60 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
1bf70 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
1bf80 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
1bf90 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
1bfa0 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
1bfb0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1bfc0 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
1bfd0 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
1bfe0 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
1bff0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
1c000 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
1c010 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
1c020 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
1c030 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
1c040 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
1c050 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
1c060 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1c070 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1c080 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
1c090 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
1c0a0 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
1c0b0 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
1c0c0 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
1c0d0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1c0e0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1c0f0 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
1c100 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1c110 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c120 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e  on] at any given
1c130 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
1c140 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1c150 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
1c160 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
1c170 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1c180 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
1c190 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
1c1a0 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
1c1b0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1c1c0 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  cleared.)^.**.**
1c1d0 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41   See also:  [PRA
1c1e0 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1c1f0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1c200 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
1c210 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
1c220 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c230 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
1c240 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
1c250 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45  ng Queries.** ME
1c260 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1c270 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65  .** This is a le
1c280 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74  gacy interface t
1c290 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64  hat is preserved
1c2a0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1c2b0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1c2c0 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74   Use of this int
1c2d0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
1c2e0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
1c2f0 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
1c300 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
1c310 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
1c320 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
1c330 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
1c340 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1c350 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
1c360 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
1c370 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
1c380 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
1c390 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
1c3a0 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
1c3b0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
1c3c0 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
1c3d0 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
1c3e0 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
1c3f0 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
1c400 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
1c410 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1c420 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
1c430 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
1c440 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
1c450 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
1c460 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1c470 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
1c480 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1c490 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
1c4a0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1c4b0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
1c4c0 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
1c4d0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1c4e0 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
1c4f0 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
1c500 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
1c510 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
1c520 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
1c530 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
1c540 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1c550 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
1c560 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
1c570 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
1c580 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
1c590 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
1c5a0 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
1c5b0 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
1c5c0 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
1c5d0 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
1c5e0 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
1c5f0 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
1c600 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1c610 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
1c620 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
1c630 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1c640 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
1c650 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
1c660 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
1c670 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
1c680 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
1c690 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
1c6a0 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
1c6b0 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
1c6c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1c6d0 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
1c6e0 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
1c6f0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
1c700 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
1c710 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
1c720 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c  * ^(As an exampl
1c730 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
1c740 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
1c750 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
1c760 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
1c770 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1c780 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1c790 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
1c7a0 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
1c7b0 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
1c7c0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
1c7d0 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
1c7e0 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
1c7f0 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
1c800 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
1c810 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
1c820 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1c830 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
1c840 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
1c850 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
1c860 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
1c870 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
1c880 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
1c890 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
1c8a0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1c8b0 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
1c8c0 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
1c8d0 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
1c8e0 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
1c8f0 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
1c900 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1c910 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
1c920 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
1c930 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
1c940 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1c950 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
1c960 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1c970 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
1c980 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1c990 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
1c9a0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1c9b0 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
1c9c0 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
1c9d0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
1c9e0 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
1c9f0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
1ca00 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
1ca10 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1ca20 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
1ca30 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1ca40 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
1ca50 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1ca60 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
1ca70 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
1ca80 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
1ca90 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
1caa0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
1cab0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
1cac0 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
1cad0 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
1cae0 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
1caf0 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
1cb00 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
1cb10 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
1cb20 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
1cb30 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
1cb40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73   application has
1cb50 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
1cb60 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73  he result from s
1cb70 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1cb80 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70  (),.** it must p
1cb90 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74  ass the result t
1cba0 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  able pointer to 
1cbb0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1cbc0 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
1cbd0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
1cbe0 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
1cbf0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
1cc00 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
1cc10 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
1cc20 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
1cc30 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
1cc40 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
1cc50 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
1cc60 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
1cc70 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
1cc80 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
1cc90 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
1cca0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1ccb0 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
1ccc0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1ccd0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
1cce0 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
1ccf0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1cd00 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
1cd10 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
1cd20 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
1cd30 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
1cd40 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
1cd50 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1cd60 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
1cd70 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
1cd80 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
1cd90 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
1cda0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
1cdb0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
1cdc0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
1cdd0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
1cde0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
1cdf0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
1ce00 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
1ce10 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
1ce20 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
1ce30 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
1ce40 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
1ce50 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
1ce60 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
1ce70 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
1ce80 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
1ce90 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1cea0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1ceb0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
1cec0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1ced0 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
1cee0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
1cef0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1cf00 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
1cf10 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
1cf20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
1cf30 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
1cf40 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
1cf50 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
1cf60 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
1cf70 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
1cf80 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
1cf90 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
1cfa0 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
1cfb0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
1cfc0 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
1cfd0 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
1cfe0 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
1cff0 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
1d000 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
1d010 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1d020 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
1d030 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
1d040 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
1d050 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
1d060 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1d070 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1d080 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
1d090 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
1d0a0 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
1d0b0 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
1d0c0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1d0d0 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20  brary..** These 
1d0e0 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74  routines underst
1d0f0 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20  and most of the 
1d100 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61  common K&R forma
1d110 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a  tting options,.*
1d120 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69  * plus some addi
1d130 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64  tional non-stand
1d140 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74  ard formats, det
1d150 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20  ailed below..** 
1d160 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f  Note that some o
1d170 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75  f the more obscu
1d180 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  re formatting op
1d190 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e  tions from recen
1d1a0 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73  t.** C-library s
1d1b0 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69  tandards are omi
1d1c0 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69  tted from this i
1d1d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
1d1e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d1f0 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1d200 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1d210 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1d220 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1d230 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1d240 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1d250 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1d260 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1d270 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1d280 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1d290 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1d2a0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1d2b0 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1d2c0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1d2d0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1d2e0 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1d2f0 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1d300 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1d310 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1d320 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1d330 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1d340 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1d350 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1d360 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1d370 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1d380 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1d390 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1d3a0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1d3b0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1d3c0 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1d3d0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1d3e0 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1d3f0 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1d400 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1d410 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1d420 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1d430 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1d440 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1d450 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1d460 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1d470 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1d480 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1d490 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1d4a0 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1d4b0 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1d4c0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1d4d0 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1d4e0 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1d4f0 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1d500 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1d510 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1d520 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1d530 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1d540 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1d550 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1d560 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1d570 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1d580 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1d590 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1d5a0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1d5b0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1d5c0 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1d5d0 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1d5e0 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1d5f0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1d600 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1d610 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1d620 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1d630 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1d640 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1d650 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1d660 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1d670 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1d680 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1d690 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1d6a0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1d6b0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1d6c0 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1d6d0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1d6e0 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1d6f0 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1d700 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1d710 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1d720 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1d730 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1d740 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1d750 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1d760 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1d770 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1d780 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1d790 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1d7a0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1d7b0 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1d7c0 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1d7d0 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1d7e0 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1d7f0 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1d800 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1d810 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1d820 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1d830 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1d840 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1d850 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1d860 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1d870 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1d880 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1d890 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70  "%w" and "%z" op
1d8a0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1d8b0 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1d8c0 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1d8d0 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1d8e0 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1d8f0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1d900 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1d910 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1d920 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1d930 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1d940 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1d950 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1d960 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1d970 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1d980 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1d990 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1d9a0 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1d9b0 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1d9c0 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1d9d0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1d9e0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1d9f0 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1da00 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1da10 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1da20 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1da30 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1da40 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1da50 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1da60 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1da70 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1da80 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1da90 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1daa0 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1dab0 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1dac0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1dad0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1dae0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1daf0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1db00 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1db10 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1db20 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1db30 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1db40 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1db50 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1db60 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1db70 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1db80 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1db90 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1dba0 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1dbb0 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1dbc0 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1dbd0 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1dbe0 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1dbf0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1dc00 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1dc10 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1dc20 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1dc30 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1dc40 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1dc50 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1dc60 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1dc70 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1dc80 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1dc90 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1dca0 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1dcb0 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1dcc0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1dcd0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1dce0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1dcf0 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1dd00 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1dd10 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1dd20 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1dd30 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1dd40 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1dd50 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1dd60 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1dd70 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1dd80 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1dd90 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1dda0 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1ddb0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1ddc0 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1ddd0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1dde0 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1ddf0 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1de00 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1de10 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1de20 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1de30 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1de40 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1de50 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1de60 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1de70 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1de80 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1de90 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1dea0 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1deb0 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1dec0 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1ded0 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1dee0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1def0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1df00 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1df10 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1df20 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1df30 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1df40 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1df50 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1df60 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1df70 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1df80 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1df90 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1dfa0 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1dfb0 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1dfc0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1dfd0 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1dfe0 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1dff0 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1e000 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1e010 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72  * ^(The "%w" for
1e020 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69  matting option i
1e030 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65  s like "%q" exce
1e040 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63  pt that it expec
1e050 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74  ts to.** be cont
1e060 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75  ained within dou
1e070 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65  ble-quotes inste
1e080 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f  ad of single quo
1e090 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65  tes, and it.** e
1e0a0 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c  scapes the doubl
1e0b0 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65  e-quote characte
1e0c0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1e0d0 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a   single-quote.**
1e0e0 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54   character.)^  T
1e0f0 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1e100 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74  ng option is int
1e110 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79  ended for safely
1e120 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61   inserting.** ta
1e130 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e  ble and column n
1e140 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73  ames into a cons
1e150 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74  tructed SQL stat
1e160 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ement..**.** ^(T
1e170 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1e180 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1e190 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1e1a0 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1e1b0 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1e1c0 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1e1d0 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1e1e0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1e1f0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1e200 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1e210 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1e220 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
1e230 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1e240 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1e250 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1e260 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1e270 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1e280 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
1e290 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1e2a0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1e2b0 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1e2c0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1e2d0 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1e2e0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1e2f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1e300 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1e310 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1e320 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1e330 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1e340 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1e350 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1e360 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1e370 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1e380 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1e390 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1e3a0 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1e3b0 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1e3c0 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1e3d0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1e3e0 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1e3f0 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1e400 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1e410 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1e420 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1e430 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e440 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1e450 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1e460 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1e470 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1e480 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1e490 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1e4a0 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1e4b0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1e4c0 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1e4d0 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1e4e0 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1e4f0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1e500 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1e510 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1e520 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1e530 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1e540 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1e550 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1e560 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1e570 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1e580 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
1e590 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1e5a0 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b  (N) routine work
1e5b0 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73  s just like.** s
1e5c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1e5d0 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1e5e0 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34  s an unsigned 64
1e5f0 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73  -bit integer ins
1e600 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67  tead.** of a sig
1e610 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67  ned 32-bit integ
1e620 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1e630 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1e640 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1e650 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1e660 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1e670 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1e680 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1e690 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1e6a0 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1e6b0 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1e6c0 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1e6d0 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1e6e0 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1e6f0 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1e700 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1e710 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1e720 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1e730 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1e740 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1e750 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1e760 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1e770 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1e780 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1e790 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1e7a0 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1e7b0 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1e7c0 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1e7d0 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1e7e0 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1e7f0 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1e800 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1e810 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1e820 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1e830 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1e840 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1e850 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1e860 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1e870 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1e880 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1e890 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1e8a0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1e8b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1e8c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e8d0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e  _realloc(X,N) in
1e8e0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1e8f0 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
1e900 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
1e910 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  ocation X to be 
1e920 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1e930 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70  ..** ^If the X p
1e940 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1e950 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1e960 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1e970 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1e980 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
1e990 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
1e9a0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1e9b0 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  c(N)..** ^If the
1e9c0 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
1e9d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1e9e0 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  X,N) is zero or.
1e9f0 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1ea00 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1ea10 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1ea20 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1ea30 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e  sqlite3_free(X).
1ea40 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1ea50 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1ea60 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1ea70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1ea80 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
1ea90 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
1eaa0 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73  e or NULL if ins
1eab0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1eac0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
1ead0 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
1eae0 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
1eaf0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
1eb00 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
1eb10 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
1eb20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
1eb30 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
1eb40 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
1eb50 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
1eb60 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
1eb70 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20  oc(X,N) and the 
1eb80 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1eb90 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
1eba0 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
1ebb0 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e  c(X,N) returns N
1ebc0 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73  ULL and N is pos
1ebd0 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a  itive, then the.
1ebe0 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  ** prior allocat
1ebf0 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64  ion is not freed
1ec00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1ec10 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58  ite3_realloc64(X
1ec20 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77  ,N) interfaces w
1ec30 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73  orks the same as
1ec40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
1ec50 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20  loc(X,N) except 
1ec60 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62  that N is a 64-b
1ec70 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
1ec80 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
1ec90 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65  f a 32-bit signe
1eca0 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  d integer..**.**
1ecb0 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f   ^If X is a memo
1ecc0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72  ry allocation pr
1ecd0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
1ece0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1ecf0 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1ed00 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1ed10 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ed20 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ), or sqlite3_re
1ed30 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a  alloc64(), then.
1ed40 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1ed50 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (X) returns the 
1ed60 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d  size of that mem
1ed70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ory allocation i
1ed80 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65  n bytes..** ^The
1ed90 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1eda0 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  by sqlite3_msize
1edb0 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72  (X) might be lar
1edc0 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d  ger than the num
1edd0 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20  ber.** of bytes 
1ede0 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58  requested when X
1edf0 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20   was allocated. 
1ee00 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c   ^If X is a NULL
1ee10 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a   pointer then.**
1ee20 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1ee30 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20  ) returns zero. 
1ee40 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20   If X points to 
1ee50 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69  something that i
1ee60 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67  s not.** the beg
1ee70 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79  inning of memory
1ee80 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20   allocation, or 
1ee90 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20  if it points to 
1eea0 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61  a formerly.** va
1eeb0 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  lid memory alloc
1eec0 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e  ation that has n
1eed0 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74  ow been freed, t
1eee0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1eef0 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d  .** of sqlite3_m
1ef00 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66  size(X) is undef
1ef10 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c  ined and possibl
1ef20 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
1ef30 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1ef40 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1ef50 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74  _malloc(), sqlit
1ef60 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a  e3_realloc(),.**
1ef70 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1ef80 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  4(), and sqlite3
1ef90 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20  _realloc64().** 
1efa0 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
1efb0 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
1efc0 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
1efd0 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
1efe0 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
1eff0 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
1f000 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
1f010 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
1f020 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
1f030 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
1f040 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
1f050 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
1f060 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
1f070 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
1f080 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
1f090 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
1f0a0 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
1f0b0 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
1f0c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
1f0d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
1f0e0 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
1f0f0 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
1f100 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
1f110 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
1f120 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1f130 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
1f140 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
1f150 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
1f160 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
1f170 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
1f180 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
1f190 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
1f1a0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1f1b0 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
1f1c0 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
1f1d0 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
1f1e0 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
1f1f0 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
1f200 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
1f210 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
1f220 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
1f230 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1f240 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
1f250 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
1f260 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
1f270 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
1f280 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
1f290 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
1f2a0 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
1f2b0 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
1f2c0 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
1f2d0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
1f2e0 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
1f2f0 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
1f300 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
1f310 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
1f320 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1f330 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
1f340 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
1f350 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
1f360 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
1f370 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
1f380 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1f390 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1f3a0 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
1f3b0 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
1f3c0 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
1f3d0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1f3e0 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
1f3f0 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
1f400 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
1f410 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
1f420 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
1f430 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
1f440 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
1f450 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1f460 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
1f470 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
1f480 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
1f490 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69  e3_malloc64(sqli
1f4a0 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
1f4b0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
1f4c0 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
1f4d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1f4e0 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73  alloc64(void*, s
1f4f0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
1f500 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1f510 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65  e(void*);.sqlite
1f520 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  3_uint64 sqlite3
1f530 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a  _msize(void*);..
1f540 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f550 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
1f560 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
1f570 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
1f580 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
1f590 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
1f5a0 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
1f5b0 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
1f5c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1f5d0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1f5e0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1f5f0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
1f600 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
1f610 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
1f620 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1f630 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
1f640 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1f650 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1f660 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1f670 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1f680 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
1f690 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
1f6a0 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
1f6b0 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
1f6c0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1f6d0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1f6e0 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
1f6f0 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
1f700 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
1f710 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1f720 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
1f730 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1f740 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
1f750 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
1f760 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1f770 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1f780 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1f790 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1f7a0 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
1f7b0 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
1f7c0 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
1f7d0 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
1f7e0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1f7f0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
1f800 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
1f810 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
1f820 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
1f830 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
1f840 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
1f850 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1f860 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
1f870 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
1f880 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
1f890 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
1f8a0 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
1f8b0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1f8c0 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
1f8d0 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
1f8e0 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
1f8f0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1f900 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
1f910 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
1f920 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
1f930 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1f940 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
1f950 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1f960 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
1f970 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
1f980 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1f990 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1f9a0 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
1f9b0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1f9c0 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
1f9d0 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
1f9e0 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
1f9f0 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
1fa00 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
1fa10 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
1fa20 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
1fa30 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
1fa40 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
1fa50 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
1fa60 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
1fa70 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
1fa80 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
1fa90 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
1faa0 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
1fab0 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
1fac0 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
1fad0 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
1fae0 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
1faf0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
1fb00 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
1fb10 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
1fb20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
1fb30 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1fb40 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
1fb50 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
1fb60 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
1fb70 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
1fb80 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
1fb90 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1fba0 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
1fbb0 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
1fbc0 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e  o buffer P..** ^
1fbd0 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20  The P parameter 
1fbe0 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  can be a NULL po
1fbf0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  inter..**.** ^If
1fc00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
1fc10 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69  s not been previ
1fc20 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20  ously called or 
1fc30 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a  if the previous.
1fc40 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65  ** call had N le
1fc50 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61  ss than one or a
1fc60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
1fc70 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52  r P, then the PR
1fc80 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20  NG is.** seeded 
1fc90 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
1fca0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
1fcb0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
1fcc0 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20  ethod of.** the 
1fcd0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1fce0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
1fcf0 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
1fd00 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
1fd10 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
1fd20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64  of 1 or more and
1fd30 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50   a.** non-NULL P
1fd40 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f   then the pseudo
1fd50 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
1fd60 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
1fd70 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
1fd80 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
1fd90 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1fda0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
1fdb0 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
1fdc0 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
1fdd0 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
1fde0 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
1fdf0 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
1fe00 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
1fe10 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
1fe20 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1fe30 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1fe40 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
1fe50 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1fe60 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
1fe70 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1fe80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
1fe90 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
1fea0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
1feb0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1fec0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1fed0 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
1fee0 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
1fef0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
1ff00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1ff10 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1ff20 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
1ff30 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
1ff40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1ff50 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
1ff60 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1ff70 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
1ff80 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
1ff90 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
1ffa0 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
1ffb0 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
1ffc0 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
1ffd0 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
1ffe0 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
1fff0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
20000 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
20010 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
20020 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
20030 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
20040 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
20050 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
20060 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
20070 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
20080 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
20090 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
200a0 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
200b0 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
200c0 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
200d0 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
200e0 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
200f0 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
20100 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
20110 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
20120 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
20130 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
20140 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20150 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
20160 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
20170 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
20180 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
20190 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
201a0 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
201b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
201c0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
201d0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
201e0 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
201f0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
20200 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
20210 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
20220 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
20230 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
20240 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
20250 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
20260 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
20270 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
20280 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
20290 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
202a0 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
202b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
202c0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
202d0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
202e0 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
202f0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
20300 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
20310 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
20320 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
20330 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
20340 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
20350 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
20360 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20370 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
20380 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
20390 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
203a0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
203b0 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
203c0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
203d0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
203e0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
203f0 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
20400 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
20410 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
20420 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
20430 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
20440 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
20450 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
20460 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
20470 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
20480 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
20490 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
204a0 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
204b0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
204c0 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
204d0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
204e0 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
204f0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
20500 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
20510 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
20520 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
20530 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
20540 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
20550 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
20560 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
20570 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
20580 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
20590 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
205a0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
205b0 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
205c0 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
205d0 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
205e0 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
205f0 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
20600 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
20610 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
20620 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
20630 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
20640 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
20650 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
20660 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
20670 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
20680 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
20690 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
206a0 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
206b0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
206c0 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
206d0 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
206e0 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
206f0 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
20700 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
20710 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
20720 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
20730 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
20740 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
20750 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
20760 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
20770 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
20780 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
20790 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
207a0 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
207b0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
207c0 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
207d0 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
207e0 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
207f0 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
20800 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
20810 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
20820 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
20830 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
20840 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
20850 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
20860 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
20870 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
20880 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
20890 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
208a0 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
208b0 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
208c0 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
208d0 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
208e0 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
208f0 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
20900 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
20910 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
20920 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
20930 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
20940 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
20950 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
20960 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
20970 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
20980 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
20990 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
209a0 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
209b0 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
209c0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
209d0 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
209e0 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
209f0 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
20a00 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
20a10 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
20a20 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
20a30 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
20a40 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
20a50 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
20a60 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
20a70 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
20a80 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
20a90 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
20aa0 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
20ab0 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
20ac0 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
20ad0 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
20ae0 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
20af0 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
20b00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
20b10 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
20b20 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
20b30 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
20b40 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
20b50 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
20b60 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
20b70 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
20b80 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
20b90 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
20ba0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
20bb0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
20bc0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
20bd0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20be0 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
20bf0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
20c00 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
20c10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20c20 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
20c30 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
20c40 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
20c50 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
20c60 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
20c70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
20c80 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
20c90 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
20ca0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
20cb0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
20cc0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
20cd0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
20ce0 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
20cf0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
20d00 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
20d10 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
20d20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
20d30 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
20d40 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
20d50 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
20d60 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
20d70 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
20d80 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
20d90 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
20da0 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
20db0 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
20dc0 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
20dd0 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
20de0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
20df0 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
20e00 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
20e10 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
20e20 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
20e30 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
20e40 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
20e50 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
20e60 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
20e70 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
20e80 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
20e90 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
20ea0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20eb0 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
20ec0 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
20ed0 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
20ee0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
20ef0 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
20f00 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
20f10 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
20f20 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
20f30 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
20f40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
20f50 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
20f60 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
20f70 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
20f80 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
20f90 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
20fa0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
20fb0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
20fc0 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
20fd0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
20fe0 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
20ff0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
21000 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
21010 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
21020 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
21030 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
21040 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
21050 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
21060 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
21070 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
21080 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
21090 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
210a0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
210b0 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
210c0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
210d0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
210e0 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
210f0 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
21100 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
21110 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
21120 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
21130 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
21140 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c  used as a [confl
21150 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d  ict resolution m
21160 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ode].** returned
21170 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
21180 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
21190 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
211a0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
211b0 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
211c0 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
211d0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
211e0 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
211f0 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
21200 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
21210 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
21220 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
21230 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
21240 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
21250 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
21260 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
21270 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
21280 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
21290 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
212a0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
212b0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
212c0 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
212d0 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
212e0 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
212f0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
21300 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
21310 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
21320 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
21330 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
21340 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
21350 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
21360 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
21370 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
21380 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
21390 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
213a0 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
213b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
213c0 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
213d0 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
213e0 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
213f0 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
21400 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
21410 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
21420 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
21430 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
21440 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
21450 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
21460 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
21470 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
21480 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
21490 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
214a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
214b0 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
214c0 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
214d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
214e0 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
214f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
21500 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
21510 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
21520 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
21530 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
21540 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
21550 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
21560 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
21570 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
21580 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
21590 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
215a0 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
215b0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
215c0 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
215d0 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
215e0 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
215f0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
21600 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
21610 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21620 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
21630 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
21640 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
21650 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21660 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
21670 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
21680 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
21690 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
216a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
216b0 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
216c0 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
216d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
216e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
216f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
21700 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
21710 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
21720 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
21730 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21740 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
21750 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
21760 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
21770 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
21780 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21790 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
217a0 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
217b0 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
217c0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
217d0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
217e0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
217f0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
21800 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
21810 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
21820 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21830 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21840 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
21850 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
21860 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
21870 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21880 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
21890 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
218a0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
218b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
218c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
218d0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
218e0 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
218f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21900 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21910 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21920 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
21930 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
21940 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
21950 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21960 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21970 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
21980 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
21990 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
219a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
219b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
219c0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
219d0 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
219e0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
219f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21a00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21a10 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
21a20 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
21a30 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21a40 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21a50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21a60 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
21a70 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
21a80 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
21a90 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
21aa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21ab0 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
21ac0 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
21ad0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
21ae0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21af0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21b00 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
21b10 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
21b20 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
21b30 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21b40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21b50 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
21b60 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
21b70 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
21b80 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21b90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
21ba0 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
21bb0 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
21bc0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
21bd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21be0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
21bf0 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
21c00 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
21c10 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
21c20 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
21c30 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
21c40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21c50 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
21c60 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
21c70 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
21c80 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
21c90 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
21ca0 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
21cb0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
21cc0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21cd0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
21ce0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
21cf0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
21d00 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
21d10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21d20 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
21d30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
21d40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21d50 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
21d60 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
21d70 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
21d80 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
21d90 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
21da0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21db0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21dc0 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
21dd0 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
21de0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
21df0 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
21e00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21e10 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
21e20 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
21e30 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
21e40 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21e50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21e60 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
21e70 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
21e80 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
21e90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21ea0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21eb0 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
21ec0 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
21ed0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21ee0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21ef0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21f00 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
21f10 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
21f20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21f30 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
21f40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21f50 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
21f60 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
21f70 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
21f80 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
21f90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21fa0 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
21fb0 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
21fc0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
21fd0 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
21fe0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21ff0 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
22000 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
22010 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
22020 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
22030 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22040 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
22050 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
22060 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64  onger used */.#d
22070 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43  efine SQLITE_REC
22080 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20  URSIVE          
22090 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    33   /* NULL  
220a0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
220b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a            */../*
220c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
220d0 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
220e0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
220f0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
22100 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
22110 74 69 6e 65 73 20 61 72 65 20 64 65 70 72 65 63  tines are deprec
22120 61 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73  ated. Use the [s
22130 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
22140 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
22150 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 72  instead of the r
22160 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69 62 65  outines describe
22170 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  d here..**.** Th
22180 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
22190 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
221a0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
221b0 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
221c0 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
221d0 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
221e0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
221f0 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
22200 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
22210 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
22220 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
22230 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
22240 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
22250 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
22260 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
22270 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
22280 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
22290 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
222a0 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
222b0 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
222c0 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
222d0 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
222e0 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
222f0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
22300 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
22310 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
22320 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
22330 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
22340 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
22350 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
22360 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
22370 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
22380 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
22390 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
223a0 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
223b0 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
223c0 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
223d0 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
223e0 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49  _TRACE_SIZE_LIMI
223f0 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
22400 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
22410 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74  ed to limit.** t
22420 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f  he length of [bo
22430 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65  und parameter] e
22440 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20  xpansion in the 
22450 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65  output of sqlite
22460 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a  3_trace()..**.**
22470 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
22480 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
22490 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
224a0 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
224b0 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
224c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
224d0 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
224e0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
224f0 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
22500 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
22510 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
22520 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
22530 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
22540 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
22550 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
22560 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
22570 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
22580 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
22590 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
225a0 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
225b0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
225c0 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
225d0 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
225e0 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
225f0 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
22600 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
22610 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
22620 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
22630 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
22640 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
22650 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
22660 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
22670 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
22680 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
22690 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
226a0 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
226b0 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
226c0 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
226d0 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
226e0 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
226f0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
22700 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50  e..*/.SQLITE_DEP
22710 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71  RECATED void *sq
22720 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
22730 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
22740 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
22750 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
22760 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
22770 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74  ATED void *sqlit
22780 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
22790 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
227a0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
227b0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
227c0 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
227d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
227e0 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76  EF: SQL Trace Ev
227f0 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ent Codes.** KEY
22800 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52  WORDS: SQLITE_TR
22810 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ACE.**.** These 
22820 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69  constants identi
22830 66 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76  fy classes of ev
22840 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62 65  ents that can be
22850 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73   monitored.** us
22860 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
22870 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61  _trace_v2()] tra
22880 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65  cing logic.  The
22890 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
228a0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  ** to [sqlite3_t
228b0 72 61 63 65 5f 76 32 28 29 5d 20 69 73 20 61 6e  race_v2()] is an
228c0 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69   OR-ed combinati
228d0 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  on of one or mor
228e0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
228f0 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e  owing constants.
22900 20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67    ^The first arg
22910 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61  ument to the tra
22920 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  ce callback.** i
22930 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  s one of the fol
22940 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  lowing constants
22950 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63  ..**.** New trac
22960 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  ing constants ma
22970 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
22980 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
22990 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61  *.** ^A trace ca
229a0 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20  llback has four 
229b0 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c  arguments: xCall
229c0 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a  back(T,C,P,X)..*
229d0 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e  * ^The T argumen
229e0 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  t is one of the 
229f0 69 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f 64  integer type cod
22a00 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68  es above..** ^Th
22a10 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e C argument is 
22a20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  a copy of the co
22a30 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61  ntext pointer pa
22a40 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
22a50 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  * fourth argumen
22a60 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  t to [sqlite3_tr
22a70 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68  ace_v2()]..** Th
22a80 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65  e P and X argume
22a90 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73  nts are pointers
22aa0 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20   whose meanings 
22ab0 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a  depend on T..**.
22ac0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
22ad0 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d  ITE_TRACE_STMT]]
22ae0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
22af0 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_STMT</dt>.** <
22b00 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
22b10 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63  ACE_STMT callbac
22b20 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
22b30 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  n a prepared sta
22b40 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20  tement.** first 
22b50 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61  begins running a
22b60 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f  nd possibly at o
22b70 74 68 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e  ther times durin
22b80 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69  g the.** executi
22b90 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61 72  on of the prepar
22ba0 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75  ed statement, su
22bb0 63 68 20 61 73 20 61 74 20 74 68 65 20 73 74 61  ch as at the sta
22bc0 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72  rt of each.** tr
22bd0 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d  igger subprogram
22be0 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  . ^The P argumen
22bf0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
22c00 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  o the.** [prepar
22c10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
22c20 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69  The X argument i
22c30 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
22c40 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a   string which.**
22c50 20 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64   is the unexpand
22c60 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74  ed SQL text of t
22c70 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
22c80 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20  ement or an SQL 
22c90 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74  comment .** that
22ca0 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 69   indicates the i
22cb0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74  nvocation of a t
22cc0 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61  rigger.  ^The ca
22cd0 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75  llback can compu
22ce0 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74  te.** the same t
22cf0 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68  ext that would h
22d00 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65  ave been returne
22d10 64 20 62 79 20 74 68 65 20 6c 65 67 61 63 79 20  d by the legacy 
22d20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
22d30 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62  ].** interface b
22d40 79 20 75 73 69 6e 67 20 74 68 65 20 58 20 61 72  y using the X ar
22d50 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65  gument when X be
22d60 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61  gins with "--" a
22d70 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b  nd invoking.** [
22d80 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
22d90 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69  _sql(P)] otherwi
22da0 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  se..**.** [[SQLI
22db0 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
22dc0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
22dd0 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e  ACE_PROFILE</dt>
22de0 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
22df0 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
22e00 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64   callback provid
22e10 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  es approximately
22e20 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66   the same.** inf
22e30 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70  ormation as is p
22e40 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 5b  rovided by the [
22e50 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
22e60 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  )] callback..** 
22e70 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
22e80 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
22e90 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
22ea0 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65  atement] and the
22eb0 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70  .** X argument p
22ec0 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69  oints to a 64-bi
22ed0 74 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  t integer which 
22ee0 69 73 20 74 68 65 20 65 73 74 69 6d 61 74 65 64  is the estimated
22ef0 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   of.** the numbe
22f00 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20  r of nanosecond 
22f10 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65  that the prepare
22f20 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  d statement took
22f30 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65   to run..** ^The
22f40 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52   SQLITE_TRACE_PR
22f50 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69  OFILE callback i
22f60 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
22f70 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  he statement fin
22f80 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ishes..**.** [[S
22f90 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d  QLITE_TRACE_ROW]
22fa0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
22fb0 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c  CE_ROW</dt>.** <
22fc0 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
22fd0 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b  ACE_ROW callback
22fe0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
22ff0 65 76 65 72 20 61 20 70 72 65 70 61 72 65 64 0a  ever a prepared.
23000 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e  ** statement gen
23010 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20  erates a single 
23020 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20  row of result.  
23030 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d  .** ^The P argum
23040 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
23050 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
23060 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
23070 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65   the.** X argume
23080 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a  nt is unused..**
23090 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
230a0 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53  CE_CLOSE]] <dt>S
230b0 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
230c0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  E</dt>.** <dd>^A
230d0 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  n SQLITE_TRACE_C
230e0 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73  LOSE callback is
230f0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
23100 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
23110 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a  ection closes..*
23120 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  * ^The P argumen
23130 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
23140 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
23150 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65  connection] obje
23160 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20  ct.** and the X 
23170 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73  argument is unus
23180 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ed..** </dl>.*/.
23190 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
231a0 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20  RACE_STMT       
231b0 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x01.#define SQL
231c0 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
231d0 45 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e  E    0x02.#defin
231e0 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  e SQLITE_TRACE_R
231f0 4f 57 20 20 20 20 20 20 20 20 30 78 30 34 0a 23  OW        0x04.#
23200 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
23210 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30  ACE_CLOSE      0
23220 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  x08../*.** CAPI3
23230 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48  REF: SQL Trace H
23240 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ook.** METHOD: s
23250 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
23260 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  e sqlite3_trace_
23270 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65  v2(D,M,X,P) inte
23280 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
23290 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  a trace callback
232a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61  .** function X a
232b0 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65  gainst [database
232c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20   connection] D, 
232d0 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d  using property m
232e0 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e  ask M.** and con
232f0 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20  text pointer P. 
23300 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62   ^If the X callb
23310 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f  ack is.** NULL o
23320 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20  r if the M mask 
23330 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72  is zero, then tr
23340 61 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65  acing is disable
23350 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67  d.  The.** M arg
23360 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
23370 74 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65  the bitwise OR-e
23380 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  d combination of
23390 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  .** zero or more
233a0 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20   [SQLITE_TRACE] 
233b0 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a  constants..**.**
233c0 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65   ^Each call to e
233d0 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72  ither sqlite3_tr
233e0 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ace() or sqlite3
233f0 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72  _trace_v2() over
23400 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65  rides .** (cance
23410 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61  ls) any prior ca
23420 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74  lls to sqlite3_t
23430 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65  race() or sqlite
23440 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a  3_trace_v2()..**
23450 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62  .** ^The X callb
23460 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
23470 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74  henever any of t
23480 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69  he events identi
23490 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b  fied by .** mask
234a0 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20   M occur.  ^The 
234b0 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20 76  integer return v
234c0 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61  alue from the ca
234d0 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e  llback is curren
234e0 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20  tly.** ignored, 
234f0 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20  though this may 
23500 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
23510 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c   releases.  Call
23520 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  back.** implemen
23530 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72  tations should r
23540 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e  eturn zero to en
23550 73 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70  sure future comp
23560 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
23570 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61   ^A trace callba
23580 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
23590 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74  th four argument
235a0 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c  s: callback(T,C,
235b0 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20  P,X)..** ^The T 
235c0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
235d0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
235e0 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e  RACE].** constan
235f0 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77  ts to indicate w
23600 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  hy the callback 
23610 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20  was invoked..** 
23620 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20  ^The C argument 
23630 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
23640 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
23650 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58  ..** The P and X
23660 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70   arguments are p
23670 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65  ointers whose me
23680 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e  anings depend on
23690 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71   T..**.** The sq
236a0 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
236b0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e   interface is in
236c0 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63  tended to replac
236d0 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  e the legacy.** 
236e0 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
236f0 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64  te3_trace()] and
23700 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
23710 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68  e()], both of wh
23720 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65  ich.** are depre
23730 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  cated..*/.int sq
23740 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a  lite3_trace_v2(.
23750 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e    sqlite3*,.  un
23760 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20  signed uMask,.  
23770 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28  int(*xCallback)(
23780 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76  unsigned,void*,v
23790 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76  oid*,void*),.  v
237a0 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a  oid *pCtx.);../*
237b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
237c0 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
237d0 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
237e0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
237f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f  ^The sqlite3_pro
23800 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c  gress_handler(D,
23810 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  N,X,P) interface
23820 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
23830 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
23840 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   X to be invoked
23850 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
23860 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
23870 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  g calls to.** [s
23880 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
23890 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
238a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65   and [sqlite3_ge
238b0 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a  t_table()] for.*
238c0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
238d0 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61  ction D.  An exa
238e0 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
238f0 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
23900 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
23910 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
23920 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
23930 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74  .** ^The paramet
23940 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74  er P is passed t
23950 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e  hrough as the on
23960 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ly parameter to 
23970 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  the .** callback
23980 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54   function X.  ^T
23990 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69  he parameter N i
239a0 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74  s the approximat
239b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
239c0 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
239d0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
239e0 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
239f0 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
23a00 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
23a10 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
23a20 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73  ack X.  ^If N is
23a30 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74   less than one t
23a40 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73  hen the progress
23a50 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64  .** handler is d
23a60 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
23a70 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
23a80 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
23a90 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
23aa0 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
23ab0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
23ac0 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
23ad0 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
23ae0 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
23af0 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
23b00 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
23b10 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
23b20 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
23b30 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
23b40 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
23b50 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
23b60 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
23b70 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
23b80 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
23b90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
23ba0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
23bb0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
23bc0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
23bd0 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
23be0 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
23bf0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
23c00 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
23c10 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
23c20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
23c30 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
23c40 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
23c50 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
23c60 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
23c70 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
23c80 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
23c90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
23ca0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
23cb0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
23cc0 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
23cd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23ce0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
23cf0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
23d00 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
23d10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
23d20 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
23d30 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
23d40 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
23d50 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  aph..**.*/.void 
23d60 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
23d70 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
23d80 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
23d90 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
23da0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23db0 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
23dc0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
23dd0 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  n.** CONSTRUCTOR
23de0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
23df0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
23e00 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
23e10 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
23e20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
23e30 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
23e40 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
23e50 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
23e60 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
23e70 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
23e80 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
23e90 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23ea0 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
23eb0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
23ec0 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
23ed0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
23ee0 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
23ef0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
23f00 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
23f10 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
23f20 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
23f30 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
23f40 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
23f50 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
23f60 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
23f70 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
23f80 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
23f90 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
23fa0 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
23fb0 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
23fc0 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
23fd0 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
23fe0 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
23ff0 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
24000 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
24010 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
24020 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
24030 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
24040 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
24050 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
24060 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
24070 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
24080 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
24090 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
240a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
240b0 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
240c0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
240d0 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
240e0 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
240f0 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
24100 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
24110 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
24120 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
24130 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
24140 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
24150 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c  lt encoding will
24160 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61   be UTF-8 for da
24170 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20  tabases created 
24180 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  using.** sqlite3
24190 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
241a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e  e3_open_v2().  ^
241b0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
241c0 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73  ding for databas
241d0 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73  es.** created us
241e0 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
241f0 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46  16() will be UTF
24200 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
24210 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
24220 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
24230 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
24240 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
24250 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
24260 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
24270 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
24280 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
24290 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
242a0 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
242b0 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
242c0 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
242d0 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
242e0 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
242f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
24300 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
24310 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
24320 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
24330 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
24340 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
24350 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
24360 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
24370 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
24380 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
24390 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
243a0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
243b0 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
243c0 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
243d0 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
243e0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
243f0 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
24400 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
24410 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
24420 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
24430 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
24440 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
24450 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
24460 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
24470 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
24480 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
24490 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
244a0 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
244b0 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
244c0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
244d0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
244e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
244f0 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
24500 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
24510 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
24520 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
24530 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
24540 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
24550 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
24560 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
24570 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
24580 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
24590 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
245a0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
245b0 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
245c0 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
245d0 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
245e0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
245f0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
24600 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
24610 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
24620 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
24630 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
24640 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
24650 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
24660 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
24670 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24680 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
24690 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
246a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
246b0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
246c0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
246d0 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
246e0 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
246f0 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
24700 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
24710 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
24720 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
24730 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
24740 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
24750 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
24760 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
24770 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
24780 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
24790 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
247a0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
247b0 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
247c0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
247d0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
247e0 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
247f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24800 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
24810 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
24820 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
24830 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
24840 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
24850 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
24860 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
24870 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
24880 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
24890 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
248a0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
248b0 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
248c0 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
248d0 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
248e0 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
248f0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
24900 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
24910 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
24920 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
24930 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
24940 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
24950 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
24960 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
24970 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
24980 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
24990 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
249a0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
249b0 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
249c0 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
249d0 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
249e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
249f0 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
24a00 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
24a10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
24a20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
24a30 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
24a40 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
24a50 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
24a60 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
24a70 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
24a80 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
24a90 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
24aa0 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
24ab0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
24ac0 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
24ad0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
24ae0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24af0 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
24b00 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
24b10 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
24b20 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
24b30 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
24b40 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
24b50 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
24b60 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
24b70 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
24b80 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
24b90 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
24ba0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
24bb0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
24bc0 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
24bd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24be0 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
24bf0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
24c00 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
24c10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
24c20 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
24c30 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
24c40 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
24c50 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
24c60 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
24c70 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
24c80 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
24c90 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
24ca0 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
24cb0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
24cc0 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
24cd0 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
24ce0 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
24cf0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24d00 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
24d10 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
24d20 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
24d30 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
24d40 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
24d50 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
24d60 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
24d70 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
24d80 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
24d90 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
24da0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
24db0 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
24dc0 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
24dd0 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
24de0 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
24df0 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
24e00 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
24e10 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
24e20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
24e30 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
24e40 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
24e50 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
24e60 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
24e70 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
24e80 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
24e90 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
24ea0 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
24eb0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
24ec0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
24ed0 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
24ee0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
24ef0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
24f00 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
24f10 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
24f20 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
24f30 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
24f40 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
24f50 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
24f60 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
24f70 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
24f80 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
24f90 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
24fa0 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
24fb0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
24fc0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
24fd0 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
24fe0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
24ff0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
25000 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
25010 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
25020 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
25030 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
25040 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
25050 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
25060 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
25070 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
25080 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
25090 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
250a0 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
250b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
250c0 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
250d0 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
250e0 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
250f0 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
25100 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
25110 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
25120 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
25130 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
25140 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
25150 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
25160 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
25170 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
25180 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
25190 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
251a0 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
251b0 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
251c0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
251d0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
251e0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
251f0 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
25200 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
25210 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
25220 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
25230 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
25240 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
25250 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
25260 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
25270 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
25280 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
25290 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
252a0 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
252b0 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
252c0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
252d0 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
252e0 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
252f0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
25300 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
25310 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
25320 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
25330 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
25340 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
25350 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
25360 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
25370 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
25380 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
25390 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
253a0 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
253b0 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
253c0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
253d0 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
253e0 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
253f0 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
25400 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
25410 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
25420 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
25430 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
25440 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
25450 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
25460 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
25470 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
25480 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77   .** ^(On window
25490 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
254a0 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
254b0 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
254c0 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
254d0 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
254e0 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  :").)^.**.** [[c
254f0 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
25500 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
25510 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
25520 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
25530 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
25540 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
25550 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
25560 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
25570 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
25580 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
25590 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
255a0 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20   SQLite and its 
255b0 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d  built-in [VFSes]
255c0 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
255d0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72  * following quer
255e0 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
255f0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
25600 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
25610 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
25620 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
25630 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
25640 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
25650 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
25660 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
25670 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
25680 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
25690 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
256a0 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
256b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
256c0 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
256d0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
256e0 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
256f0 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
25700 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
25710 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
25720 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
25730 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
25740 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
25750 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
25760 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
25770 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
25780 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
25790 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
257a0 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
257b0 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
257c0 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
257d0 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
257e0 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
257f0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
25800 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
25810 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
25820 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
25830 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
25840 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
25850 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
25860 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
25870 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
25880 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
25890 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
258a0 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
258b0 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
258c0 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
258d0 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
258e0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
258f0 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
25900 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
25910 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
25920 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
25930 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
25940 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
25950 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
25960 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
25970 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74  open_v2(). ^If t
25980 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
25990 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
259a0 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
259b0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
259c0 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
259d0 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
259e0 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
259f0 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
25a00 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
25a10 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
25a20 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
25a30 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
25a40 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
25a50 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
25a60 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
25a70 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
25a80 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
25a90 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
25aa0 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  E.  ^If the mode
25ab0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
25ac0 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79    set to "memory
25ad0 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69  " then a pure [i
25ae0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
25af0 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65  e] that never re
25b00 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72  ads.**     or wr
25b10 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69  ites from disk i
25b20 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61  s used. ^It is a
25b30 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69  n error to speci
25b40 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a  fy a value for.*
25b50 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70  *     the mode p
25b60 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
25b70 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
25b80 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
25b90 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
25ba0 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64  the flags passed
25bb0 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
25bc0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
25bd0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
25be0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
25bf0 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
25c00 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
25c10 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
25c20 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
25c30 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
25c40 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
25c50 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
25c60 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
25c70 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
25c80 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
25c90 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
25ca0 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
25cb0 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
25cc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25cd0 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
25ce0 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
25cf0 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
25d00 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
25d10 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
25d20 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
25d30 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
25d40 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
25d50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
25d60 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
25d70 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
25d80 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
25d90 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
25da0 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
25db0 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
25dc0 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62  vior requested b
25dd0 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
25de0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
25df0 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
25e00 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
25e10 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a  ACHE flag..**.**
25e20 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f    <li> <b>psow</
25e30 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61  b>: ^The psow pa
25e40 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65  rameter indicate
25e50 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  s whether or not
25e60 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77   the.**     [pow
25e70 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65  ersafe overwrite
25e80 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20  ] property does 
25e90 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c  or does not appl
25ea0 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  y to the.**     
25eb0 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e  storage media on
25ec0 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62   which the datab
25ed0 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73  ase file resides
25ee0 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
25ef0 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68  >nolock</b>: ^Th
25f00 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74  e nolock paramet
25f10 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
25f20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a  query parameter.
25f30 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20  **     which if 
25f40 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c  set disables fil
25f50 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c  e locking in rol
25f60 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f  lback journal mo
25f70 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20  des.  This.**   
25f80 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20    is useful for 
25f90 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61  accessing a data
25fa0 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79  base on a filesy
25fb0 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e  stem that does n
25fc0 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72  ot.**     suppor
25fd0 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74  t locking.  Caut
25fe0 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63  ion:  Database c
25ff0 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20  orruption might 
26000 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a  result if two.**
26010 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f       or more pro
26020 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20  cesses write to 
26030 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
26040 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66  e and any one of
26050 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72   those.**     pr
26060 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c  ocesses uses nol
26070 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  ock=1..**.**  <l
26080 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c  i> <b>immutable<
26090 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61  /b>: ^The immuta
260a0 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ble parameter is
260b0 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
260c0 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65  .**     paramete
260d0 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  r that indicates
260e0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
260f0 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65  se file is store
26100 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64  d on.**     read
26110 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57  -only media.  ^W
26120 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73  hen immutable is
26130 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73   set, SQLite ass
26140 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
26150 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69       database fi
26160 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  le cannot be cha
26170 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20  nged, even by a 
26180 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67  process with hig
26190 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69  her.**     privi
261a0 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  lege, and so the
261b0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
261c0 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e  ned read-only an
261d0 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a  d all locking.**
261e0 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20       and change 
261f0 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73  detection is dis
26200 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a  abled.  Caution:
26210 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d   Setting the imm
26220 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72  utable.**     pr
26230 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61  operty on a data
26240 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64  base file that d
26250 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e  oes in fact chan
26260 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a  ge can result.**
26270 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63       in incorrec
26280 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  t query results 
26290 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43  and/or [SQLITE_C
262a0 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a  ORRUPT] errors..
262b0 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a  **     See also:
262c0 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49   [SQLITE_IOCAP_I
262d0 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20  MMUTABLE]..**   
262e0 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a      .** </ul>.**
262f0 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
26300 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
26310 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
26320 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
26330 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
26340 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
26350 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
26360 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
26370 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
26380 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
26390 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
263a0 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
263b0 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
263c0 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
263d0 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
263e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
263f0 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
26400 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
26410 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
26420 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
26430 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
26440 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
26450 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
26460 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
26470 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
26480 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
26490 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
264a0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
264b0 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
264c0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
264d0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
264e0 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
264f0 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
26500 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
26510 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
26520 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26530 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
26540 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
26550 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
26560 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
26570 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
26580 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
26590 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
265a0 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
265b0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
265c0 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
265d0 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
265e0 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
265f0 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
26600 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
26610 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
26620 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
26630 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
26640 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
26650 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
26660 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
26670 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
26680 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
26690 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
266a0 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
266b0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
266c0 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
266d0 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
266e0 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
266f0 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
26700 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
26710 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
26720 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
26730 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
26740 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
26750 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
26760 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
26770 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
26780 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
26790 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
267a0 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
267b0 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
267c0 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
267d0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
267e0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
267f0 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
26800 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
26810 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
26820 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
26830 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
26840 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
26850 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
26860 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
26870 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
26880 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
26890 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
268a0 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20  fs=unix-dotfile 
268b0 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <td>.**         
268c0 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d   Open file "/hom
268d0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
268e0 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c   Use the special
268f0 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69   VFS "unix-dotfi
26900 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  le".**          
26910 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69  that uses dot-fi
26920 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  les in place of 
26930 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c  posix advisory l
26940 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c  ocking..** <tr><
26950 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
26960 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
26970 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
26980 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
26990 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
269a0 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
269b0 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
269c0 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
269d0 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI hex
269e0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
269f0 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20  sequences (%HH) 
26a00 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
26a10 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
26a20 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
26a30 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
26a40 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
26a50 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
26a60 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
26a70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
26a80 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
26a90 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
26aa0 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
26ab0 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
26ac0 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
26ad0 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
26ae0 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
26af0 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
26b00 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
26b10 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
26b20 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
26b30 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
26b40 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
26b50 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
26b60 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
26b70 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
26b80 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
26b90 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
26ba0 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
26bb0 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
26bc0 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
26bd0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
26be0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
26bf0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
26c00 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
26c10 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
26c20 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
26c30 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
26c40 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
26c50 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
26c60 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
26c70 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
26c80 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
26c90 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
26ca0 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
26cb0 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
26cc0 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
26cd0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
26ce0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
26cf0 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
26d00 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
26d10 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
26d20 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
26d30 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
26d40 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
26d50 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
26d60 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
26d70 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
26d80 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
26d90 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
26da0 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  g sqlite3_open()
26db0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
26dc0 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73  _v2().  Otherwis
26dd0 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
26de0 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
26df0 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
26e00 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
26e10 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ay fail..**.** S
26e20 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
26e30 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
26e40 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
26e50 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
26e60 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
26e70 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
26e80 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
26e90 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
26ea0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
26eb0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
26ec0 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
26ed0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
26ee0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
26ef0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
26f00 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
26f10 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
26f20 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
26f30 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
26f40 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
26f50 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
26f60 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
26f70 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
26f80 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
26f90 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
26fa0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
26fb0 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
26fc0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
26fd0 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
26fe0 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
26ff0 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
27000 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
27010 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
27020 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
27030 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
27040 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
27050 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
27060 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
27070 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c  * These are util
27080 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73  ity routines, us
27090 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
270a0 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
270b0 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65  t check.** to se
270c0 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
270d0 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
270e0 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
270f0 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
27100 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
27110 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
27120 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
27130 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  t query paramete
27140 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73  r..**.** If F is
27150 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
27160 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
27170 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
27180 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66  Open() method of
27190 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65   .** a VFS imple
271a0 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
271b0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
271c0 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61  er to xOpen() ha
271d0 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72  s one or .** mor
271e0 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
271f0 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53  _OPEN_URI] or [S
27200 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
27210 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64  DB] bits set and
27220 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d  .** P is the nam
27230 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
27240 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a  arameter, then.*
27250 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  * sqlite3_uri_pa
27260 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
27270 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  urns the value o
27280 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d  f the P.** param
27290 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74  eter if it exist
272a0 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s or a NULL poin
272b0 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  ter if P does no
272c0 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a  t appear as a .*
272d0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
272e0 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73  r on F.  If P is
272f0 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74   a query paramet
27300 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e  er of F.** has n
27310 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65  o explicit value
27320 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
27330 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
27340 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  ) returns.** a p
27350 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70  ointer to an emp
27360 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
27370 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
27380 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
27390 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20  routine assumes 
273a0 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c  that P is a bool
273b0 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ean.** parameter
273c0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75   and returns tru
273d0 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28  e (1) or false (
273e0 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  0) according to 
273f0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  the value.** of 
27400 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  P.  The sqlite3_
27410 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
27420 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  B) routine retur
27430 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74  ns true (1) if t
27440 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71  he.** value of q
27450 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
27460 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22   is one of "yes"
27470 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e  , "true", or "on
27480 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65  " in any.** case
27490 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
274a0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
274b0 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20  on-zero number. 
274c0 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   The .** sqlite3
274d0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
274e0 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ,B) routines ret
274f0 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69  urns false (0) i
27500 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  f the value of.*
27510 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
27520 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e  r P is one of "n
27530 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20  o", "false", or 
27540 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73  "off" in any cas
27550 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76  e or.** if the v
27560 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
27570 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e   a numeric zero.
27580 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20    If P is not a 
27590 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
275a0 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68  er on F or if th
275b0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
275c0 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61  does not match a
275d0 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f  ny of the.** abo
275e0 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ve, then sqlite3
275f0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
27600 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d  ,B) returns (B!=
27610 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  0)..**.** The sq
27620 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
27630 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  F,P,D) routine c
27640 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75  onverts the valu
27650 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a  e of P into a.**
27660 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
27670 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72  nteger and retur
27680 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c  ns that integer,
27690 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20   or D if P does 
276a0 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49  not.** exist.  I
276b0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
276c0 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74   is something ot
276d0 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65  her than an inte
276e0 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72  ger, then.** zer
276f0 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
27700 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20  * .** If F is a 
27710 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
27720 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
27730 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
27740 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a  turns NULL and.*
27750 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
27760 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
27770 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73  urns B.  If F is
27780 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   not a NULL poin
27790 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f  ter and.** is no
277a0 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
277b0 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74  e pathname point
277c0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70  er that SQLite p
277d0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
277e0 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68  Open.** VFS meth
277f0 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
27800 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
27810 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e  utine is undefin
27820 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a  ed and probably.
27830 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ** undesirable..
27840 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
27850 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
27860 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20  eter(const char 
27870 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73  *zFilename, cons
27880 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b  t char *zParam);
27890 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69  .int sqlite3_uri
278a0 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63  _boolean(const c
278b0 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73  har *zFile, cons
278c0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20  t char *zParam, 
278d0 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73  int bDefault);.s
278e0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
278f0 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63  ite3_uri_int64(c
27900 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73  onst char*, cons
27910 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
27920 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _int64);.../*.**
27930 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
27940 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
27950 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ges.** METHOD: s
27960 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66  qlite3.**.** ^If
27970 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
27980 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
27990 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77  all associated w
279a0 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ith .** [databas
279b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
279c0 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  failed, then the
279d0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
279e0 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  (D) interface.**
279f0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
27a00 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
27a10 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
27a20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
27a30 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c   that.** API cal
27a40 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73  l..** If the mos
27a50 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
27a60 6c 20 77 61 73 20 73 75 63 63 65 73 73 66 75 6c  l was successful
27a70 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
27a80 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
27a90 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
27aa0 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  ) is undefined..
27ab0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
27ac0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
27ad0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
27ae0 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
27af0 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
27b00 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
27b10 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
27b20 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
27b30 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
27b40 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
27b50 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
27b60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
27b70 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
27b80 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
27b90 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
27ba0 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
27bb0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
27bc0 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
27bd0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
27be0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
27bf0 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
27c00 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
27c10 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
27c20 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
27c30 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
27c40 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
27c50 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
27c60 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
27c70 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
27c80 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
27c90 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
27ca0 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
27cb0 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
27cc0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
27cd0 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
27ce0 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
27cf0 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ns.)^.**.** ^The
27d00 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28   sqlite3_errstr(
27d10 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
27d20 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d  rns the English-
27d30 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a  language text.**
27d40 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
27d50 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  the [result code
27d60 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20  ], as UTF-8..** 
27d70 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
27d80 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
27d90 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
27da0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  aged internally.
27db0 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20  ** and must not 
27dc0 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20  be freed by the 
27dd0 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a  application)^..*
27de0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
27df0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
27e00 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
27e10 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
27e20 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
27e30 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
27e40 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
27e50 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
27e60 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
27e70 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
27e80 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
27e90 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
27ea0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
27eb0 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
27ec0 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
27ed0 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
27ee0 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
27ef0 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
27f00 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
27f10 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
27f20 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
27f30 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
27f40 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
27f50 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
27f60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
27f70 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
27f80 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
27f90 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
27fa0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
27fb0 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
27fc0 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
27fd0 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
27fe0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
27ff0 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
28000 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
28010 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
28020 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
28030 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
28040 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
28050 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
28060 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
28070 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
28080 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
28090 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
280a0 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
280b0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
280c0 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
280d0 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
280e0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
280f0 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
28100 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  e set..*/.int sq
28110 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
28120 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20  lite3 *db);.int 
28130 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
28140 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
28150 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61   *db);.const cha
28160 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
28170 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  g(sqlite3*);.con
28180 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
28190 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
281a0 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  3*);.const char 
281b0 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28  *sqlite3_errstr(
281c0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
281d0 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20  I3REF: Prepared 
281e0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
281f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
28200 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28210 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
28220 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
28230 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
28240 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
28250 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
28260 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
28270 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  .** has been com
28280 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72  piled into binar
28290 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65  y form and is re
282a0 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61  ady to be evalua
282b0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b  ted..**.** Think
282c0 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61   of each SQL sta
282d0 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61  tement as a sepa
282e0 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72  rate computer pr
282f0 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f  ogram.  The.** o
28300 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
28310 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e   is source code.
28320 20 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61    A prepared sta
28330 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a  tement object .*
28340 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65  * is the compile
28350 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20  d object code.  
28360 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20  All SQL must be 
28370 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
28380 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
28390 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74  tement before it
283a0 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a   can be run..**.
283b0 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c  ** The life-cycl
283c0 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20  e of a prepared 
283d0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
283e0 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69   usually goes li
283f0 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
28400 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
28410 74 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20  te the prepared 
28420 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
28430 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
28440 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a  prepare_v2()]..*
28450 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
28460 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  es to [parameter
28470 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
28480 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
28490 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
284a0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
284b0 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
284c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
284d0 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
284e0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
284f0 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
28500 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
28510 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
28520 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
28530 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
28540 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
28550 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
28560 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
28570 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
28580 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
28590 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
285a0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
285b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
285c0 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
285d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
285e0 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20  -time Limits.** 
285f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
28600 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
28610 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
28620 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
28630 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
28640 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
28650 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
28660 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
28670 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
28680 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
28690 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
286a0 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
286b0 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
286c0 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
286d0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
286e0 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
286f0 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
28700 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
28710 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
28720 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
28730 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
28740 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
28750 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
28760 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
28770 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a  t construct.)^.*
28780 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
28790 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
287a0 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
287b0 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
287c0 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61  ged..** ^(For ea
287d0 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  ch limit categor
287e0 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c  y SQLITE_LIMIT_<
287f0 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65  i>NAME</i> there
28800 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
28810 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
28820 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20  ound].** set at 
28830 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20  compile-time by 
28840 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  a C preprocessor
28850 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a   macro called.**
28860 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54   [limits | SQLIT
28870 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  E_MAX_<i>NAME</i
28880 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  >]..** (The "_LI
28890 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
288a0 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
288b0 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e  "_MAX_".))^.** ^
288c0 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
288d0 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
288e0 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
288f0 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
28900 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
28910 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
28920 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a  per bound..**.**
28930 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
28940 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
28950 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61  he limit was cha
28960 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73  nged, the .** [s
28970 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20  qlite3_limit()] 
28980 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28990 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  s the prior valu
289a0 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a  e of the limit..
289b0 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69  ** ^Hence, to fi
289c0 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  nd the current v
289d0 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20  alue of a limit 
289e0 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67  without changing
289f0 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69   it,.** simply i
28a00 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72  nvoke this inter
28a10 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68  face with the th
28a20 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65  ird parameter se
28a30 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52  t to -1..**.** R
28a40 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un-time limits a
28a50 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
28a60 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
28a70 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
28a80 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
28a90 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
28aa0 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
28ab0 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
28ac0 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
28ad0 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
28ae0 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
28af0 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
28b00 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
28b10 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74  ** web browser t
28b20 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
28b30 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
28b40 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
28b50 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
28b60 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
28b70 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
28b80 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
28b90 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
28ba0 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
28bb0 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
28bc0 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
28bd0 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
28be0 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
28bf0 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
28c00 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
28c10 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
28c20 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
28c30 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
28c40 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
28c50 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
28c60 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
28c70 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
28c80 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
28c90 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
28ca0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
28cb0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
28cc0 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
28cd0 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
28ce0 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
28cf0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
28d00 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
28d10 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
28d20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
28d30 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
28d40 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
28d50 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
28d60 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
28d70 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
28d80 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
28d90 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74  releases..*/.int
28da0 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
28db0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
28dc0 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
28dd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
28de0 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
28df0 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57  tegories.** KEYW
28e00 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
28e10 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
28e20 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
28e30 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
28e40 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
28e50 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
28e60 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
28e70 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
28e80 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
28e90 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
28ea0 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
28eb0 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
28ec0 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
28ed0 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
28ee0 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
28ef0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
28f00 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
28f10 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
28f20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
28f30 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
28f40 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
28f50 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
28f60 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  IMIT_LENGTH</dt>
28f70 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
28f80 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20  mum size of any 
28f90 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f  string or BLOB o
28fa0 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20  r table row, in 
28fb0 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a  bytes.<dd>)^.**.
28fc0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
28fd0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e  T_SQL_LENGTH]] ^
28fe0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
28ff0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
29000 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29010 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
29020 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
29030 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29   in bytes.</dd>)
29040 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
29050 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20  _LIMIT_COLUMN]] 
29060 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29070 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
29080 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29090 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
290a0 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
290b0 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
290c0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
290d0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
290e0 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
290f0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
29100 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
29110 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
29120 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
29130 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
29140 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29150 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e  T_EXPR_DEPTH]] ^
29160 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
29170 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74  T_EXPR_DEPTH</dt
29180 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29190 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68  imum depth of th
291a0 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20  e parse tree on 
291b0 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c  any expression.<
291c0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
291d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
291e0 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28  OUND_SELECT]] ^(
291f0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29200 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
29210 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
29220 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
29230 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f  of terms in a co
29240 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74  mpound SELECT st
29250 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a  atement.</dd>)^.
29260 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29270 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e  IMIT_VDBE_OP]] ^
29280 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
29290 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
292a0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
292b0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
292c0 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
292d0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
292e0 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
292f0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
29300 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68  L statement.  Th
29310 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  is limit is not 
29320 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66  currently.** enf
29330 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68  orced, though th
29340 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65  at might be adde
29350 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  d in some future
29360 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
29370 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  QLite.</dd>)^.**
29380 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29390 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
293a0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
293b0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
293c0 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
293d0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
293e0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
293f0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
29400 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
29410 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
29420 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  D]] ^(<dt>SQLITE
29430 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
29440 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29450 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
29460 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
29470 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
29480 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  )^</dd>.**.** [[
29490 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
294a0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
294b0 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
294c0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
294d0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
294e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
294f0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
29500 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
29510 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45  ent to the [LIKE
29520 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f  ] or.** [GLOB] o
29530 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e  perators.</dd>)^
29540 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
29550 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
29560 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  UMBER]].** ^(<dt
29570 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
29580 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
29590 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
295a0 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62  ximum index numb
295b0 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d  er of any [param
295c0 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20  eter] in an SQL 
295d0 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a  statement.)^.**.
295e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
295f0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d  T_TRIGGER_DEPTH]
29600 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
29610 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
29620 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
29630 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
29640 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f   of recursion fo
29650 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e  r triggers.</dd>
29660 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29670 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
29680 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53  HREADS]] ^(<dt>S
29690 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
296a0 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a  ER_THREADS</dt>.
296b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
296c0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78  um number of aux
296d0 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68  iliary worker th
296e0 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e  reads that a sin
296f0 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  gle.** [prepared
29700 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20   statement] may 
29710 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  start.</dd>)^.**
29720 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
29730 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
29740 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
29750 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
29760 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29770 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
29780 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
29790 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
297a0 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
297b0 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
297c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
297d0 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
297e0 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
297f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29800 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
29810 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
29820 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29830 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
29840 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
29850 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29860 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
29870 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
29880 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29890 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
298a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
298b0 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
298c0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
298d0 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
298e0 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
298f0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
29900 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
29910 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
29920 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
29930 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
29940 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
29950 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
29960 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20  _THREADS        
29970 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     11../*.** CAP
29980 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
29990 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
299a0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
299b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
299c0 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  mpiler}.** METHO
299d0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f  D: sqlite3.** CO
299e0 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
299f0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f  e3_stmt.**.** To
29a00 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
29a10 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
29a20 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
29a30 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
29a40 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
29a50 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
29a60 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
29a70 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
29a80 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
29a90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
29aa0 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
29ab0 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
29ac0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
29ad0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
29ae0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
29af0 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
29b00 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
29b10 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
29b20 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
29b30 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
29b40 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
29b50 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
29b60 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
29b70 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
29b80 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
29b90 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
29ba0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
29bb0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
29bc0 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
29bd0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
29be0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
29bf0 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
29c00 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
29c10 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
29c20 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
29c30 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
29c40 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72  ^If the nByte ar
29c50 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69  gument is negati
29c60 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ve, then zSql is
29c70 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
29c80 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
29c90 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
29ca0 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c  yte is positive,
29cb0 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a   then it is the.
29cc0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
29cd0 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
29ce0 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73  l.  ^If nByte is
29cf0 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70   zero, then no p
29d00 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
29d10 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65  ment is generate
29d20 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
29d30 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74  ler knows that t
29d40 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
29d50 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
29d60 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  ated, then.** th
29d70 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70  ere is a small p
29d80 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
29d90 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20  tage to passing 
29da0 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
29db0 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68  er that.** is th
29dc0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
29dd0 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
29de0 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
29df0 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
29e00 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  l-terminator..**
29e10 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
29e20 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
29e30 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
29e40 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
29e50 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
29e60 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
29e70 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
29e80 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
29e90 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
29ea0 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
29eb0 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
29ec0 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
29ed0 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
29ee0 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
29ef0 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
29f00 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
29f10 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
29f20 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
29f30 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
29f40 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
29f50 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
29f60 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
29f70 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
29f80 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
29f90 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
29fa0 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
29fb0 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
29fc0 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
29fd0 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
29fe0 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
29ff0 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
2a000 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
2a010 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
2a020 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
2a030 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
2a040 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
2a050 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
2a060 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
2a070 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
2a080 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
2a090 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
2a0a0 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
2a0b0 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
2a0c0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
2a0d0 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
2a0e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2a0f0 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
2a100 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
2a110 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
2a120 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
2a130 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
2a140 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2a150 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2a160 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2a170 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
2a180 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
2a190 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
2a1a0 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
2a1b0 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
2a1c0 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
2a1d0 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
2a1e0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
2a1f0 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
2a200 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
2a210 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
2a220 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
2a230 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2a240 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
2a250 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
2a260 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
2a270 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
2a280 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
2a290 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
2a2a0 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
2a2b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
2a2c0 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
2a2d0 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
2a2e0 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
2a2f0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
2a300 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
2a310 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
2a320 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
2a330 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
2a340 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
2a350 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
2a360 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
2a370 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2a380 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
2a390 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
2a3a0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
2a3b0 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
2a3c0 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61   it again. As ma
2a3d0 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41  ny as [SQLITE_MA
2a3e0 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a  X_SCHEMA_RETRY].
2a3f0 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20  ** retries will 
2a400 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c  occur before sql
2a410 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65  ite3_step() give
2a420 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73  s up and returns
2a430 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f   an error..** </
2a440 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
2a450 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
2a460 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
2a470 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
2a480 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
2a490 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
2a4a0 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
2a4b0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2a4c0 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
2a4d0 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
2a4e0 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
2a4f0 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
2a500 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
2a510 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
2a520 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
2a530 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
2a540 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
2a550 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
2a560 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
2a570 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
2a580 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
2a590 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
2a5a0 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
2a5b0 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
2a5c0 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
2a5d0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
2a5e0 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
2a5f0 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
2a600 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
2a610 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
2a620 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
2a630 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
2a640 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
2a650 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
2a660 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
2a670 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
2a680 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
2a690 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
2a6a0 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
2a6b0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
2a6c0 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
2a6d0 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
2a6e0 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
2a6f0 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
2a700 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
2a710 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
2a720 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
2a730 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
2a740 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
2a750 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
2a760 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2a770 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
2a780 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
2a790 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
2a7a0 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
2a7b0 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
2a7c0 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
2a7d0 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
2a7e0 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
2a7f0 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
2a800 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2a810 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
2a820 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
2a830 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
2a840 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
2a850 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
2a860 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
2a870 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
2a880 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2a890 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT3] compile-t
2a8a0 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
2a8b0 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  abled..** </li>.
2a8c0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
2a8d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2a8e0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2a8f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2a900 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2a910 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2a920 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2a930 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2a940 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2a950 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2a960 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2a970 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2a980 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2a990 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2a9a0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2a9b0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2a9c0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2a9d0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2a9e0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2a9f0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2aa00 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
2aa10 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2aa20 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
2aa30 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2aa40 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2aa50 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2aa60 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2aa70 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2aa80 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2aa90 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2aaa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2aab0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2aac0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2aad0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2aae0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2aaf0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2ab00 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2ab10 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2ab20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2ab30 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2ab40 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2ab50 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2ab60 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
2ab70 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2ab80 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2ab90 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2aba0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2abb0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2abc0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2abd0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2abe0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2abf0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2ac00 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2ac10 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2ac20 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2ac30 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2ac40 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2ac50 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2ac60 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2ac70 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2ac80 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2ac90 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2aca0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2acb0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2acc0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2acd0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2ace0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2acf0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2ad00 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2ad10 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2ad20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2ad30 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2ad40 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2ad50 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2ad60 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2ad70 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2ad80 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2ad90 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2ada0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
2adb0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2adc0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2add0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2ade0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2adf0 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
2ae00 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
2ae10 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2ae20 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2ae30 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20   sqlite3_sql(P) 
2ae40 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2ae50 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2ae60 20 63 6f 70 79 20 6f 66 20 74 68 65 20 55 54 46   copy of the UTF
2ae70 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  -8.** SQL text u
2ae80 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 5b 70  sed to create [p
2ae90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2aea0 74 5d 20 50 20 69 66 20 50 20 77 61 73 0a 2a 2a  t] P if P was.**
2aeb0 20 63 72 65 61 74 65 64 20 62 79 20 65 69 74 68   created by eith
2aec0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
2aed0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
2aee0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2aef0 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  v2()]..** ^The s
2af00 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2af10 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65  sql(P) interface
2af20 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2af30 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a  er to a UTF-8.**
2af40 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
2af50 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78 74 20  ng the SQL text 
2af60 6f 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  of prepared stat
2af70 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20  ement P with.** 
2af80 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
2af90 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a  s] expanded..**.
2afa0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2afb0 2c 20 69 66 20 61 20 70 72 65 70 61 72 65 64 20  , if a prepared 
2afc0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72 65  statement is cre
2afd0 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 53  ated using the S
2afe0 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c 45  QL.** text "SELE
2aff0 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e  CT $abc,:xyz" an
2b000 64 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 24  d if parameter $
2b010 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f 20  abc is bound to 
2b020 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a 20  integer 2345.** 
2b030 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a 78  and parameter :x
2b040 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74  yz is unbound, t
2b050 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  hen sqlite3_sql(
2b060 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ) will return.**
2b070 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
2b080 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24 61  ring, "SELECT $a
2b090 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71 6c  bc,:xyz" but sql
2b0a0 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2b0b0 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  l().** will retu
2b0c0 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35 2c  rn "SELECT 2345,
2b0d0 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  NULL".)^.**.** ^
2b0e0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61  The sqlite3_expa
2b0f0 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65 72  nded_sql() inter
2b100 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c  face returns NUL
2b110 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
2b120 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61  t memory.** is a
2b130 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64  vailable to hold
2b140 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72 20   the result, or 
2b150 69 66 20 74 68 65 20 72 65 73 75 6c 74 20 77 6f  if the result wo
2b160 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a  uld exceed the.*
2b170 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 74  * the maximum st
2b180 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74 65  ring length dete
2b190 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b 53  rmined by the [S
2b1a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2b1b0 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  TH]..**.** ^The 
2b1c0 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
2b1d0 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
2b1e0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69  e-time option li
2b1f0 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66  mits the size of
2b200 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d 65  .** bound parame
2b210 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20  ter expansions. 
2b220 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d   ^The [SQLITE_OM
2b230 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c  IT_TRACE] compil
2b240 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
2b250 20 63 61 75 73 65 73 20 73 71 6c 69 74 65 33 5f   causes sqlite3_
2b260 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 74  expanded_sql() t
2b270 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  o always return 
2b280 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
2b290 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64   string returned
2b2a0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28   by sqlite3_sql(
2b2b0 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20 62 79  P) is managed by
2b2c0 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a   SQLite and is.*
2b2d0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
2b2e0 66 72 65 65 64 20 77 68 65 6e 20 74 68 65 20 70  freed when the p
2b2f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b300 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a  t is finalized..
2b310 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72  ** ^The string r
2b320 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2b330 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2b340 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65 72  P), on the other
2b350 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74   hand,.** is obt
2b360 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2b370 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
2b380 64 20 6d 75 73 74 20 62 65 20 66 72 65 65 20 62  d must be free b
2b390 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
2b3a0 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e 67 20  n.** by passing 
2b3b0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  it to [sqlite3_f
2b3c0 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  ree()]..*/.const
2b3d0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
2b3e0 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
2b3f0 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72 20 2a 73  *pStmt);.char *s
2b400 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2b410 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
2b420 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2b430 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
2b440 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
2b450 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
2b460 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20  The Database.** 
2b470 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2b480 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2b490 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2b4a0 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61  donly(X) interfa
2b4b0 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
2b4c0 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a  (non-zero) if.**
2b4d0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
2b4e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b4f0 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f  ment] X makes no
2b500 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20   direct changes 
2b510 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  to.** the conten
2b520 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
2b530 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  e file..**.** No
2b540 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61  te that [applica
2b550 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2b560 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a   functions] or.*
2b570 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
2b580 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  s] might change 
2b590 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64  the database ind
2b5a0 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64  irectly as a sid
2b5b0 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e  e effect.  .** ^
2b5c0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
2b5d0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2b5e0 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69  defines a functi
2b5f0 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74  on "eval()" that
2b600 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69   .** calls [sqli
2b610 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65  te3_exec()], the
2b620 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
2b630 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f  SQL statement wo
2b640 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  uld.** change th
2b650 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
2b660 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66  through side-eff
2b670 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  ects:.**.** <blo
2b680 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
2b690 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28      SELECT eval(
2b6a0 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27  'DELETE FROM t1'
2b6b0 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f  ) FROM t2;.** </
2b6c0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2b6d0 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61  >.**.** But beca
2b6e0 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  use the [SELECT]
2b6f0 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
2b700 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  not change the d
2b710 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
2b720 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65  directly, sqlite
2b730 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2b740 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65  ) would still re
2b750 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a  turn true.)^.**.
2b760 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20  ** ^Transaction 
2b770 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e  control statemen
2b780 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49  ts such as [BEGI
2b790 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52  N], [COMMIT], [R
2b7a0 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41  OLLBACK],.** [SA
2b7b0 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52  VEPOINT], and [R
2b7c0 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71  ELEASE] cause sq
2b7d0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2b7e0 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
2b7f0 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74  true,.** since t
2b800 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  he statements th
2b810 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20  emselves do not 
2b820 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20  actually modify 
2b830 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
2b840 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20  .** rather they 
2b850 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69  control the timi
2b860 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72  ng of when other
2b870 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69   statements modi
2b880 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62  fy the .** datab
2b890 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41  ase.  ^The [ATTA
2b8a0 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d  CH] and [DETACH]
2b8b0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f   statements also
2b8c0 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65   cause.** sqlite
2b8d0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2b8e0 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
2b8f0 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68   since, while th
2b900 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  ose statements.*
2b910 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e  * change the con
2b920 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20  figuration of a 
2b930 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b940 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74  ion, they do not
2b950 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65   make .** change
2b960 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74  s to the content
2b970 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2b980 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a   files on disk..
2b990 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b9a0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2b9b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2b9c0 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45 47 49  s true for [BEGI
2b9d0 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42 45 47  N] since.** [BEG
2b9e0 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74 73 20  IN] merely sets 
2b9f0 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73 2c 20  internal flags, 
2ba00 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e 7c 42  but the [BEGIN|B
2ba10 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45 5d 20  EGIN IMMEDIATE] 
2ba20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42 45  and.** [BEGIN|BE
2ba30 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d 20 63  GIN EXCLUSIVE] c
2ba40 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75 63 68  ommands do touch
2ba50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
2ba60 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d so.** sqlite3_
2ba70 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2ba80 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 66 6f  returns false fo
2ba90 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e 64 73  r those commands
2baa0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2bab0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73  _stmt_readonly(s
2bac0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2bad0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2bae0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
2baf0 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  If A Prepared St
2bb00 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e  atement Has Been
2bb10 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44   Reset.** METHOD
2bb20 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2bb30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2bb40 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69  3_stmt_busy(S) i
2bb50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2bb60 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
2bb70 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   if the.** [prep
2bb80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2bb90 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70  S has been stepp
2bba0 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65  ed at least once
2bbb0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2bbc0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74  te3_step(S)] but
2bbd0 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e   has neither run
2bbe0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28   to completion (
2bbf0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
2bc00 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b  ITE_DONE] from [
2bc10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2bc20 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65  ) nor.** been re
2bc30 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  set using [sqlit
2bc40 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e  e3_reset(S)].  ^
2bc50 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2bc60 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65  _busy(S).** inte
2bc70 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61  rface returns fa
2bc80 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55  lse if S is a NU
2bc90 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20  LL pointer.  If 
2bca0 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e  S is not a .** N
2bcb0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ULL pointer and 
2bcc0 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72  is not a pointer
2bcd0 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65   to a valid [pre
2bce0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2bcf0 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e  .** object, then
2bd00 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2bd10 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
2bd20 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
2bd30 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ble..**.** This 
2bd40 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
2bd50 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61   used in combina
2bd60 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65  tion [sqlite3_ne
2bd70 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f  xt_stmt()].** to
2bd80 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70   locate all prep
2bd90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20  ared statements 
2bda0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2bdb0 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63  a database .** c
2bdc0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61  onnection that a
2bdd0 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65  re in need of be
2bde0 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73  ing reset.  This
2bdf0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a   can be used,.**
2be00 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e   for example, in
2be10 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74   diagnostic rout
2be20 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66  ines to search f
2be30 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20  or prepared .** 
2be40 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
2be50 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72  are holding a tr
2be60 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a  ansaction open..
2be70 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
2be80 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33  tmt_busy(sqlite3
2be90 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2bea0 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
2beb0 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
2bec0 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
2bed0 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
2bee0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
2bef0 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
2bf00 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
2bf10 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
2bf20 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2bf30 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
2bf40 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
2bf50 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
2bf60 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
2bf70 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
2bf80 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
2bf90 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
2bfa0 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
2bfb0 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
2bfc0 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
2bfd0 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
2bfe0 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
2bff0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2c000 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
2c010 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
2c020 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
2c030 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
2c040 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
2c050 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
2c060 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
2c070 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2c080 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
2c090 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
2c0a0 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
2c0b0 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
2c0c0 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
2c0d0 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
2c0e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c0f0 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
2c100 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
2c110 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
2c120 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
2c130 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
2c140 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
2c150 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
2c160 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
2c170 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
2c180 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74  value_dup()] int
2c190 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2c1a0 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20  ed to construct 
2c1b0 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63  a new .** protec
2c1c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c1d0 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74  e from an unprot
2c1e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c1f0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
2c200 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
2c210 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
2c220 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
2c230 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
2c240 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
2c250 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
2c260 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
2c270 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2c280 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c290 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
2c2a0 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
2c2b0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2c2c0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c2d0 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
2c2e0 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
2c2f0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
2c300 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
2c310 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
2c320 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
2c330 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
2c340 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
2c350 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
2c360 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
2c370 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
2c380 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
2c390 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2c3a0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
2c3b0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
2c3c0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
2c3d0 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
2c3e0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
2c3f0 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
2c400 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2c410 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
2c420 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
2c430 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
2c440 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
2c450 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
2c460 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
2c470 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
2c480 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
2c490 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
2c4a0 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
2c4b0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
2c4c0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
2c4d0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2c4e0 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
2c4f0 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
2c500 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
2c510 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
2c520 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
2c530 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
2c540 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
2c550 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
2c560 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
2c570 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2c580 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
2c590 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
2c5a0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2c5b0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2c5c0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2c5d0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2c5e0 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
2c5f0 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
2c600 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2c610 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
2c620 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
2c630 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2c640 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
2c650 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2c660 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
2c670 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
2c680 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
2c690 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
2c6a0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
2c6b0 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
2c6c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2c6d0 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
2c6e0 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
2c6f0 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
2c700 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
2c710 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
2c720 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
2c730 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
2c740 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
2c750 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
2c760 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
2c770 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
2c780 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
2c790 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
2c7a0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
2c7b0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
2c7c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
2c7d0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2c7e0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2c7f0 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
2c800 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2c810 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
2c820 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
2c830 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
2c840 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
2c850 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
2c860 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
2c870 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
2c880 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2c890 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2c8a0 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
2c8b0 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
2c8c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2c8d0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
2c8e0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
2c8f0 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
2c900 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
2c910 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
2c920 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2c930 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
2c940 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
2c950 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c960 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
2c970 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
2c980 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
2c990 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
2c9a0 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
2c9b0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
2c9c0 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
2c9d0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
2c9e0 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
2c9f0 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
2ca00 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
2ca10 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2ca20 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  _stmt.**.** ^(In
2ca30 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2ca40 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
2ca50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ca60 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
2ca70 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
2ca80 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
2ca90 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
2caa0 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
2cab0 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
2cac0 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
2cad0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2cae0 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
2caf0 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
2cb00 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
2cb10 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
2cb20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2cb30 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
2cb40 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
2cb50 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
2cb60 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
2cb70 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
2cb80 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
2cb90 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
2cba0 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
2cbb0 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
2cbc0 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
2cbd0 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
2cbe0 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
2cbf0 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
2cc00 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
2cc10 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2cc20 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
2cc30 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
2cc40 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2cc50 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
2cc60 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2cc70 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
2cc80 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
2cc90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2cca0 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
2ccb0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
2ccc0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2ccd0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
2cce0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
2ccf0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2cd00 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2cd10 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
2cd20 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
2cd30 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
2cd40 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2cd50 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
2cd60 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
2cd70 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
2cd80 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
2cd90 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
2cda0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2cdb0 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
2cdc0 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
2cdd0 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
2cde0 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
2cdf0 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
2ce00 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
2ce10 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
2ce20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
2ce30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2ce40 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2ce50 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
2ce60 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
2ce70 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
2ce80 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
2ce90 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
2cea0 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
2ceb0 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
2cec0 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
2ced0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
2cee0 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
2cef0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2cf00 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
2cf10 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
2cf20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
2cf30 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
2cf40 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
2cf50 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
2cf60 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
2cf70 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2cf80 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
2cf90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2cfa0 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  xt16().** or sql
2cfb0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2cfc0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2cfd0 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  er then the four
2cfe0 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  th parameter.** 
2cff0 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74  is ignored and t
2d000 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73  he end result is
2d010 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c   the same as sql
2d020 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29  ite3_bind_null()
2d030 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
2d040 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
2d050 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
2d060 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
2d070 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2d080 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2d090 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
2d0a0 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
2d0b0 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
2d0c0 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
2d0d0 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
2d0e0 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
2d0f0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
2d100 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
2d110 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2d120 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2d130 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
2d140 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2d150 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  ).** is negative
2d160 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74  , then the lengt
2d170 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
2d180 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
2d190 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
2d1a0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
2d1b0 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
2d1c0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2d1d0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2d1e0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2d1f0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a  negative, then.*
2d200 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  * the behavior i
2d210 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2d220 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  If a non-negativ
2d230 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2d240 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  er is provided t
2d250 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2d260 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ext().** or sqli
2d270 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2d280 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2d290 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a  d_text64() then.
2d2a0 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  ** that paramete
2d2b0 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
2d2c0 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
2d2d0 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
2d2e0 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
2d2f0 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
2d300 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
2d310 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
2d320 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
2d330 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
2d340 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
2d350 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
2d360 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
2d370 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
2d380 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
2d390 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
2d3a0 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
2d3b0 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
2d3c0 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
2d3d0 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
2d3e0 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
2d3f0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
2d400 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2d410 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
2d420 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42  ment to the BLOB
2d430 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64   and string bind
2d440 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ing interfaces.*
2d450 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  * is a destructo
2d460 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
2d470 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
2d480 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
2d490 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
2d4a0 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
2d4b0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2d4c0 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
2d4d0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
2d4e0 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
2d4f0 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
2d500 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e   bind API fails.
2d510 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
2d520 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
2d530 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
2d540 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
2d550 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
2d560 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
2d570 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
2d580 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
2d590 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
2d5a0 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
2d5b0 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
2d5c0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2d5d0 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
2d5e0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
2d5f0 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
2d600 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
2d610 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
2d620 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
2d630 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
2d640 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
2d650 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2d660 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
2d670 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67  * ^The sixth arg
2d680 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2d690 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d  _bind_text64() m
2d6a0 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a  ust be one of.**
2d6b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
2d6c0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
2d6d0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2d6e0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
2d6f0 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63  16LE].** to spec
2d700 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ify the encoding
2d710 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20   of the text in 
2d720 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2d730 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  ter.  If.** the 
2d740 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2d750 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2d760 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f  ext64() is not o
2d770 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c  ne of the.** all
2d780 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77  owed values show
2d790 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74  n above, or if t
2d7a0 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
2d7b0 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a   is different.**
2d7c0 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69   from the encodi
2d7d0 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ng specified by 
2d7e0 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65  the sixth parame
2d7f0 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ter, then the be
2d800 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64  havior.** is und
2d810 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2d820 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2d830 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
2d840 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
2d850 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
2d860 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
2d870 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
2d880 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
2d890 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
2d8a0 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
2d8b0 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
2d8c0 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
2d8d0 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
2d8e0 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
2d8f0 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
2d900 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
2d910 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
2d920 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
2d930 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
2d940 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
2d950 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
2d960 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
2d970 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
2d980 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
2d990 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
2d9a0 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
2d9b0 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
2d9c0 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
2d9d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2d9e0 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49 2c 50  nd_pointer(S,I,P
2d9f0 29 20 72 6f 75 74 69 6e 65 20 63 61 75 73 65 73  ) routine causes
2da00 20 74 68 65 20 49 2d 74 68 20 70 61 72 61 6d 65   the I-th parame
2da10 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 70 61  ter in.** [prepa
2da20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2da30 20 74 6f 20 68 61 76 65 20 61 6e 20 53 51 4c 20   to have an SQL 
2da40 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c 20 62  value of NULL, b
2da50 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a  ut to also be.**
2da60 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2da70 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50 2e 0a   the pointer P..
2da80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2da90 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29 20 72  bind_pointer() r
2daa0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
2dab0 65 64 20 74 6f 20 70 61 73 73 0a 2a 2a 20 68 6f  ed to pass.** ho
2dac0 73 74 2d 6c 61 6e 67 75 61 67 65 20 70 6f 69 6e  st-language poin
2dad0 74 65 72 73 20 69 6e 74 6f 20 5b 61 70 70 6c 69  ters into [appli
2dae0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2daf0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
2db00 2a 20 5e 41 20 70 61 72 61 6d 65 74 65 72 20 74  * ^A parameter t
2db10 68 61 74 20 69 73 20 69 6e 69 74 69 61 6c 69 7a  hat is initializ
2db20 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
2db30 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29  3_bind_pointer()
2db40 5d 20 61 70 70 65 61 72 73 0a 2a 2a 20 74 6f 20  ] appears.** to 
2db50 62 65 20 61 6e 20 6f 72 64 69 6e 61 72 79 20 53  be an ordinary S
2db60 51 4c 20 4e 55 4c 4c 20 76 61 6c 75 65 20 74 6f  QL NULL value to
2db70 20 65 76 65 72 79 74 68 69 6e 67 20 6f 74 68 65   everything othe
2db80 72 20 74 68 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  r than.** [sqlit
2db90 65 33 5f 76 61 6c 75 65 5f 70 6f 69 6e 74 65 72  e3_value_pointer
2dba0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  ()]..**.** ^If a
2dbb0 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
2dbc0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2dbd0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
2dbe0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
2dbf0 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
2dc00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2dc10 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
2dc20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2dc30 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
2dc40 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2dc50 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
2dc60 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
2dc70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2dc80 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
2dc90 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
2dca0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2dcb0 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
2dcc0 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
2dcd0 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
2dce0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2dcf0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
2dd00 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
2dd10 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
2dd20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
2dd30 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
2dd40 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
2dd50 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
2dd60 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
2dd70 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
2dd80 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
2dd90 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
2dda0 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
2ddb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2ddc0 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
2ddd0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
2dde0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
2ddf0 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
2de00 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
2de10 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
2de20 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f  .** ^[SQLITE_TOO
2de30 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65  BIG] might be re
2de40 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69  turned if the si
2de50 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f  ze of a string o
2de60 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64  r BLOB.** exceed
2de70 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64  s limits imposed
2de80 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
2de90 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
2dea0 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a  T_LENGTH]) or.**
2deb0 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e   [SQLITE_MAX_LEN
2dec0 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  GTH]..** ^[SQLIT
2ded0 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
2dee0 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
2def0 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
2df00 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
2df10 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
2df20 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2df30 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
2df40 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2df50 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2df60 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2df70 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2df80 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2df90 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
2dfa0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2dfb0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
2dfc0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2dfd0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2dfe0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2dff0 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
2e000 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2e010 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
2e020 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74  lob64(sqlite3_st
2e030 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2e040 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
2e050 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
2e060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2e070 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2e080 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2e090 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2e0a0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
2e0b0 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
2e0c0 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
2e0d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
2e0e0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
2e0f0 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
2e100 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
2e110 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
2e120 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2e130 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
2e140 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
2e150 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2e160 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2e170 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e  t,const char*,in
2e180 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
2e190 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2e1a0 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
2e1b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2e1c0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2e1d0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2e1e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2e1f0 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65  nd_text64(sqlite
2e200 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2e210 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
2e220 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
2e230 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e240 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64      void(*)(void
2e250 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61  *), unsigned cha
2e260 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74  r encoding);.int
2e270 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
2e280 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
2e290 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
2e2a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2e2b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2e2c0 70 6f 69 6e 74 65 72 28 73 71 6c 69 74 65 33 5f  pointer(sqlite3_
2e2d0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  stmt*, int, void
2e2e0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2e2f0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
2e300 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e310 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71  , int n);.int sq
2e320 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2e330 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74  lob64(sqlite3_st
2e340 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
2e350 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a  3_uint64);../*.*
2e360 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2e370 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
2e380 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ters.** METHOD: 
2e390 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2e3a0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
2e3b0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2e3c0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
2e3d0 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
2e3e0 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
2e3f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2e400 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
2e410 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
2e420 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
2e430 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
2e440 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
2e450 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
2e460 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
2e470 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
2e480 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
2e490 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
2e4a0 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
2e4b0 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
2e4c0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   time..**.** ^(T
2e4d0 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
2e4e0 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
2e4f0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
2e500 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
2e510 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
2e520 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
2e530 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
2e540 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
2e550 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
2e560 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
2e570 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
2e580 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
2e590 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c  N form are used,
2e5a0 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
2e5b0 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
2e5c0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
2e5d0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2e5e0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2e5f0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2e600 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2e610 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
2e620 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2e630 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2e640 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
2e650 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2e660 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
2e670 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2e680 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
2e690 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
2e6a0 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ter.** METHOD: s
2e6b0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2e6c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2e6d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2e6e0 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(P,N) interfac
2e6f0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  e returns.** the
2e700 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74   name of the N-t
2e710 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  h [SQL parameter
2e720 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] in the [prepar
2e730 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
2e740 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65  .** ^(SQL parame
2e750 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
2e760 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
2e770 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
2e780 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
2e790 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
2e7a0 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
2e7b0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
2e7c0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
2e7d0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
2e7e0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
2e7f0 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
2e800 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
2e810 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
2e820 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
2e830 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20   the name.)^.** 
2e840 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74  ^Parameters of t
2e850 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
2e860 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
2e870 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
2e880 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
2e890 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
2e8a0 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e  nameless" or "an
2e8b0 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
2e8c0 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rs"..**.** ^The 
2e8d0 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
2e8e0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
2e8f0 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
2e900 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c  *.** ^If the val
2e910 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue N is out of r
2e920 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e  ange or if the N
2e930 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
2e940 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
2e950 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
2e960 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ned.  ^The retur
2e970 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
2e980 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
2e990 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
2e9a0 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
2e9b0 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
2e9c0 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
2e9d0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
2e9e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2e9f0 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
2ea00 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2ea10 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
2ea20 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2ea30 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2ea40 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2ea50 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2ea60 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
2ea70 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2ea80 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2ea90 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  ex()]..*/.const 
2eaa0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
2eab0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2eac0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2ead0 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
2eae0 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
2eaf0 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
2eb00 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
2eb10 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2eb20 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  3_stmt.**.** ^Re
2eb30 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
2eb40 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
2eb50 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
2eb60 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65  e.  ^The.** inde
2eb70 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
2eb80 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
2eb90 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
2eba0 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
2ebb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
2ebc0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2ebd0 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a  nd()].  ^A zero.
2ebe0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
2ebf0 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
2ec00 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
2ec10 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
2ec20 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
2ec30 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
2ec40 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
2ec50 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
2ec60 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
2ec70 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
2ec80 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2ec90 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2eca0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2ecb0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2ecc0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2ecd0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2ece0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2ecf0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2ed00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2ed10 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2ed20 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2ed30 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2ed40 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
2ed50 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
2ed60 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
2ed70 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
2ed80 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
2ed90 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2eda0 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
2edb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2edc0 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
2edd0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
2ede0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
2edf0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
2ee00 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
2ee10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2ee20 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
2ee30 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2ee40 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
2ee50 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
2ee60 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
2ee70 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
2ee80 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
2ee90 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
2eea0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
2eeb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2eec0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
2eed0 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
2eee0 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   Set.** 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 6e  ** ^Return the n
2ef10 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2ef20 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
2ef30 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
2ef40 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2ef50 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66 20  statement]. ^If 
2ef60 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
2ef70 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d 65 61  urns 0, that mea
2ef80 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70  ns the .** [prep
2ef90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2efa0 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74 61 20  returns no data 
2efb0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
2efc0 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48  [UPDATE])..** ^H
2efd0 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62 65 63  owever, just bec
2efe0 61 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ause this routin
2eff0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69  e returns a posi
2f000 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f 65 73  tive number does
2f010 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68 61   not.** mean tha
2f020 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f  t one or more ro
2f030 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c 6c 20  ws of data will 
2f040 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 41  be returned.  ^A
2f050 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
2f060 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73  t.** will always
2f070 20 68 61 76 65 20 61 20 70 6f 73 69 74 69 76 65   have a positive
2f080 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f090 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65 70 65  count() but depe
2f0a0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a 20  nding on the.** 
2f0b0 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
2f0c0 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 65  straints and the
2f0d0 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c 20   table content, 
2f0e0 69 74 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  it might return 
2f0f0 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53  no rows..**.** S
2f100 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2f110 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a  3_data_count()].
2f120 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2f130 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
2f140 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2f150 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f160 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
2f170 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
2f180 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2f190 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2f1a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
2f1b0 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
2f1c0 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
2f1d0 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
2f1e0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
2f1f0 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
2f200 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68   statement.  ^Th
2f210 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2f220 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
2f230 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2f240 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
2f250 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
2f260 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
2f270 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2f280 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
2f290 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
2f2a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
2f2b0 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
2f2c0 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72    ^The first par
2f2d0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
2f2e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f2f0 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
2f300 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
2f310 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54  T] statement. ^T
2f320 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2f330 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
2f340 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54  lumn number.  ^T
2f350 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2f360 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
2f370 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
2f380 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
2f390 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
2f3a0 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
2f3b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f3c0 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
2f3d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
2f3e0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
2f3f0 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
2f400 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
2f410 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
2f420 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
2f430 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2f440 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
2f450 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
2f460 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
2f470 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
2f480 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2f490 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2f4a0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
2f4b0 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
2f4c0 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
2f4d0 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
2f4e0 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
2f4f0 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
2f500 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
2f510 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
2f520 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
2f530 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
2f540 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
2f550 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2f560 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
2f570 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
2f580 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
2f590 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
2f5a0 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
2f5b0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
2f5c0 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
2f5d0 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
2f5e0 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
2f5f0 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
2f600 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
2f610 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
2f620 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
2f630 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
2f640 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
2f650 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e  the next..*/.con
2f660 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2f670 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
2f680 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2f690 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
2f6a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2f6b0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2f6c0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
2f6d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
2f6e0 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
2f6f0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
2f700 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2f710 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2f720 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
2f730 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
2f740 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61  determine the da
2f750 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
2f760 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75  nd.** table colu
2f770 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f  mn that is the o
2f780 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69  rigin of a parti
2f790 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c  cular result col
2f7a0 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43  umn in.** [SELEC
2f7b0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  T] statement..**
2f7c0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
2f7d0 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
2f7e0 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
2f7f0 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
2f800 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
2f810 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
2f820 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61  ing.  ^The _data
2f830 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
2f840 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
2f850 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
2f860 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
2f870 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
2f880 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
2f890 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
2f8a0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
2f8b0 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  olumn name..** ^
2f8c0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2f8d0 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
2f8e0 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
2f8f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
2f900 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
2f910 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
2f920 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
2f930 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2f940 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
2f950 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
2f960 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
2f970 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2f980 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
2f990 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
2f9a0 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
2f9b0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
2f9c0 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
2f9d0 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
2f9e0 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54  coding..**.** ^T
2f9f0 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
2fa00 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
2fa10 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
2fa20 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
2fa30 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
2fa40 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
2fa50 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
2fa60 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e  ment to these in
2fa70 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70  terfaces is a [p
2fa80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fa90 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  t]..** ^These fu
2faa0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
2fab0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
2fac0 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
2fad0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
2fae0 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
2faf0 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
2fb00 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
2fb10 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
2fb20 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20   ^The left-most 
2fb30 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e  column is column
2fb40 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75   0 for these rou
2fb50 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tines..**.** ^If
2fb60 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2fb70 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
2fb80 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
2fb90 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
2fba0 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
2fbb0 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
2fbc0 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
2fbd0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2fbe0 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
2fbf0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
2fc00 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
2fc10 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
2fc20 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
2fc30 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
2fc40 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65   ^Otherwise, the
2fc50 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
2fc60 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
2fc70 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
2fc80 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20  e,.** or column 
2fc90 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
2fca0 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
2fcb0 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
2fcc0 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20  ** ^As with all 
2fcd0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
2fce0 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e  s, those whose n
2fcf0 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31  ames end with "1
2fd00 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
2fd10 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
2fd20 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65  ngs and the othe
2fd30 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
2fd40 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
2fd50 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20  ^These APIs are 
2fd60 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
2fd70 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
2fd80 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
2fd90 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
2fda0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
2fdb0 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
2fdc0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a  essor symbol..**
2fdd0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
2fde0 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
2fdf0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
2fe00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
2fe10 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
2fe20 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
2fe30 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
2fe40 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2fe50 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2fe60 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
2fe70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ed..**.** If two
2fe80 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
2fe90 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
2fea0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
2feb0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2fec0 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
2fed0 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
2fee0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
2fef0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ff00 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
2ff10 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68   column.** at th
2ff20 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
2ff30 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2ff40 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63   undefined..*/.c
2ff50 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2ff60 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2ff70 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
2ff80 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2ff90 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2ffa0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2ffb0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2ffc0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2ffd0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2ffe0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
2fff0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
30000 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
30010 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
30020 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
30030 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
30040 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
30050 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
30060 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
30070 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
30080 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
30090 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
300a0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
300b0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
300c0 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
300d0 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
300e0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
300f0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
30100 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  _stmt.**.** ^(Th
30110 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
30120 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
30130 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
30140 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
30150 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
30160 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
30170 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
30180 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
30190 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
301a0 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
301b0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
301c0 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
301d0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
301e0 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
301f0 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
30200 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
30210 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
30220 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
30230 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
30240 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
30250 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
30260 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
30270 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
30280 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
30290 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
302a0 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
302b0 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
302c0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
302d0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
302e0 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
302f0 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
30300 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
30310 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
30320 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
30330 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
30340 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
30350 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
30360 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
30370 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
30380 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
30390 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
303a0 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
303b0 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
303c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
303d0 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
303e0 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
303f0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
30400 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
30410 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
30420 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
30430 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
30440 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
30450 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
30460 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
30470 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
30480 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
30490 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
304a0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
304b0 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
304c0 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
304d0 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
304e0 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
304f0 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
30500 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
30510 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
30520 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
30530 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
30540 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
30550 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
30560 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
30570 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
30580 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
30590 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
305a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
305b0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
305c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
305d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
305e0 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
305f0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
30600 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
30610 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  _stmt.**.** Afte
30620 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
30630 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
30640 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
30650 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69   either.** [sqli
30660 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
30670 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
30680 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
30690 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
306a0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
306b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
306c0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
306d0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
306e0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
306f0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
30700 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
30710 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
30720 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
30730 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
30740 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
30750 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
30760 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
30770 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
30780 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
30790 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
307a0 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
307b0 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
307c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
307d0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
307e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
307f0 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
30800 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
30810 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
30820 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
30830 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
30840 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
30850 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
30860 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
30870 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
30880 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
30890 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
308a0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
308b0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
308c0 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
308d0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
308e0 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
308f0 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
30900 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
30910 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
30920 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
30930 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
30940 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
30950 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
30960 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
30970 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
30980 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
30990 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
309a0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
309b0 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
309c0 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
309d0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
309e0 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
309f0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
30a00 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
30a10 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
30a20 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
30a30 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
30a40 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
30a50 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
30a60 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
30a70 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
30a80 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
30a90 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
30aa0 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
30ab0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
30ac0 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
30ad0 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
30ae0 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
30af0 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70  within an.** exp
30b00 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
30b10 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
30b20 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
30b30 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
30b40 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
30b50 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
30b60 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
30b70 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
30b80 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
30b90 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
30ba0 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
30bb0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
30bc0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
30bd0 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
30be0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
30bf0 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
30c00 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
30c10 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
30c20 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
30c30 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
30c40 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
30c50 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
30c60 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
30c70 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
30c80 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
30c90 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
30ca0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
30cb0 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
30cc0 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
30cd0 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
30ce0 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
30cf0 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
30d00 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
30d10 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
30d20 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
30d30 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
30d40 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
30d50 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
30d60 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
30d70 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
30d80 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
30d90 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
30da0 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
30db0 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
30dc0 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
30dd0 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
30de0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
30df0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
30e00 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
30e10 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
30e20 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
30e30 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
30e40 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
30e50 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
30e60 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
30e70 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
30e80 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
30e90 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
30ea0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
30eb0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
30ec0 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
30ed0 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
30ee0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
30ef0 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
30f00 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
30f10 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
30f20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30f30 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
30f40 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
30f50 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
30f60 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
30f70 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
30f80 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
30f90 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
30fa0 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
30fb0 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
30fc0 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
30fd0 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
30fe0 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
30ff0 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
31000 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31010 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
31020 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
31030 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
31040 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
31050 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
31060 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
31070 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
31080 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
31090 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
310a0 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
310b0 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
310c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
310d0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
310e0 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
310f0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
31100 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
31110 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
31120 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
31130 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
31140 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
31150 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
31160 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
31170 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
31180 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
31190 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
311a0 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
311b0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
311c0 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
311d0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
311e0 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
311f0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
31200 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
31210 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
31220 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
31230 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
31240 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
31250 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
31260 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
31270 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
31280 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 5b  ().  But after [
31290 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31  version 3.6.23.1
312a0 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32  ] ([dateof:3.6.2
312b0 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  3.1],.** sqlite3
312c0 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
312d0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
312e0 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
312f0 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
31300 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
31310 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
31320 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
31330 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
31340 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
31350 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
31360 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
31370 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
31380 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
31390 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
313a0 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
313b0 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
313c0 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
313d0 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
313e0 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
313f0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
31400 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
31410 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
31420 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
31430 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
31440 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
31450 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
31460 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
31470 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
31480 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
31490 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
314a0 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
314b0 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
314c0 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
314d0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
314e0 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
314f0 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
31500 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
31510 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
31520 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
31530 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
31540 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
31550 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
31560 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
31570 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
31580 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
31590 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
315a0 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
315b0 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
315c0 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
315d0 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
315e0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
315f0 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
31600 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
31610 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
31620 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
31630 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
31640 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
31650 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
31660 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
31670 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
31680 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
31690 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
316a0 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
316b0 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
316c0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
316d0 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
316e0 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
316f0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
31700 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
31710 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
31720 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
31730 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
31740 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
31750 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
31760 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
31770 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
31780 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt set.** METHOD
31790 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
317a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
317b0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
317c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
317d0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
317e0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
317f0 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  * current row of
31800 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
31810 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
31820 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49  tement] P..** ^I
31830 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
31840 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20  ment P does not 
31850 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61  have results rea
31860 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  dy to return.** 
31870 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68  (via calls to th
31880 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
31890 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  n_int | sqlite3_
318a0 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a  column_*()] of.*
318b0 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68  * interfaces) th
318c0 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  en sqlite3_data_
318d0 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73  count(P) returns
318e0 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69   0..** ^The sqli
318f0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
31900 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72  ) routine also r
31910 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73  eturns 0 if P is
31920 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
31930 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31940 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
31950 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
31960 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
31970 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
31980 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
31990 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44  turned [SQLITE_D
319a0 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  ONE].  ^The sqli
319b0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
319c0 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e  ).** will return
319d0 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65   non-zero if pre
319e0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73  vious call to [s
319f0 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
31a00 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
31a10 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74  ITE_ROW], except
31a20 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   in the case of 
31a30 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72  the [PRAGMA incr
31a40 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a  emental_vacuum].
31a50 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61  ** where it alwa
31a60 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20  ys returns zero 
31a70 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20  since each step 
31a80 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74  of that multi-st
31a90 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74  ep.** pragma ret
31aa0 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f  urns 0 columns o
31ab0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65  f data..**.** Se
31ac0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
31ad0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
31ae0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
31af0 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
31b00 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
31b10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31b20 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
31b30 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
31b40 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
31b50 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
31b60 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
31b70 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
31b80 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
31b90 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
31ba0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
31bb0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
31bc0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
31bd0 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
31be0 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
31bf0 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
31c00 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
31c10 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
31c20 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
31c30 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
31c40 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
31c50 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
31c60 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
31c70 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
31c80 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
31c90 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
31ca0 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
31cb0 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
31cc0 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
31cd0 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
31ce0 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
31cf0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
31d00 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
31d10 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
31d20 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
31d30 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
31d40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
31d50 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
31d60 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
31d70 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
31d80 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
31d90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31da0 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
31db0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
31dc0 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
31dd0 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
31de0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
31df0 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
31e00 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
31e10 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
31e20 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
31e30 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
31e40 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
31e50 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
31e60 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f  ctions}.** METHO
31e70 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
31e80 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
31e90 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
31ea0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
31eb0 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
31ec0 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
31ed0 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
31ee0 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65   query.  ^In eve
31ef0 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
31f00 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
31f10 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
31f20 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
31f30 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
31f40 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
31f50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
31f60 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
31f70 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
31f80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
31f90 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
31fa0 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
31fb0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
31fc0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
31fd0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
31fe0 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
31ff0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
32000 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
32010 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
32020 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
32030 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
32040 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  ndex 0..** ^The 
32050 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
32060 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
32070 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
32080 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
32090 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
320a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
320b0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
320c0 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
320d0 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
320e0 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
320f0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
32100 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
32110 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
32120 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
32130 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
32140 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
32150 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
32160 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
32170 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
32180 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
32190 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
321a0 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
321b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
321c0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
321d0 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
321e0 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
321f0 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
32200 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
32210 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
32220 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
32230 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
32240 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
32250 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
32260 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
32270 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
32280 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
32290 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
322a0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
322b0 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
322c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
322d0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
322e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
322f0 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
32300 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
32310 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
32320 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
32330 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
32340 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
32350 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
32360 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
32370 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32380 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
32390 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
323a0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
323b0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
323c0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
323d0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
323e0 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
323f0 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
32400 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
32410 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
32420 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
32430 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
32440 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
32450 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
32460 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
32470 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
32480 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
32490 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
324a0 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
324b0 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
324c0 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
324d0 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
324e0 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
324f0 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
32500 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
32510 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
32520 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
32530 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
32540 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
32550 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
32560 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
32570 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
32580 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
32590 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
325a0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
325b0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
325c0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
325d0 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
325e0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
325f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
32600 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
32610 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
32620 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
32630 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
32640 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
32650 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
32660 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
32670 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32680 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
32690 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
326a0 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
326b0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
326c0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
326d0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
326e0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
326f0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
32700 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
32710 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
32720 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
32730 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
32740 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
32750 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
32760 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
32770 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
32780 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
32790 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
327a0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
327b0 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73  _bytes() returns
327c0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   zero..**.** ^If
327d0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
327e0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20   BLOB or UTF-16 
327f0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
32800 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32810 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74  ytes16().** rout
32820 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
32830 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
32840 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
32850 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
32860 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
32870 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65  TF-8 string, the
32880 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
32890 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65  _bytes16() conve
328a0 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
328b0 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20  g to UTF-16 and 
328c0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
328d0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
328e0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
328f0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
32900 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
32910 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32920 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  16() uses.** [sq
32930 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
32940 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
32950 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
32960 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72  -16 string and r
32970 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
32980 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
32990 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
329a0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
329b0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
329c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
329d0 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a  es16() returns z
329e0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ero..**.** ^The 
329f0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
32a00 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
32a10 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
32a20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
32a30 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64  umn_bytes16()] d
32a40 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  o not include th
32a50 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
32a60 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  rs at the end.**
32a70 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
32a80 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74   ^For clarity: t
32a90 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
32aa0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
32ab0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
32ac0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
32ad0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
32ae0 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20   are the number 
32af0 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
32b00 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
32b10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
32b20 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
32b30 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
32b40 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
32b50 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
32b60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32b70 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
32b80 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
32b90 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  e always zero-te
32ba0 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
32bb0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
32bc0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
32bd0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
32be0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
32bf0 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  B is a NULL poin
32c00 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61  ter..**.** <b>Wa
32c10 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20  rning:</b> ^The 
32c20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
32c30 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
32c40 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
32c50 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
32c60 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
32c70 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d   object.  In a m
32c80 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e 76  ultithreaded env
32c90 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20  ironment,.** an 
32ca0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
32cb0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
32cc0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
32cd0 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a  d safely with.**
32ce0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
32cf0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
32d00 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
32d10 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
32d20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
32d30 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
32d40 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
32d50 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
32d60 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
32d70 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
32d80 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
32d90 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
32da0 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
32db0 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
32dc0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
32dd0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
32de0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
32df0 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76  es()], the behav
32e00 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ior is not threa
32e10 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dsafe..**.** The
32e20 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
32e30 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
32e40 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
32e50 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f  ppropriate.  ^Fo
32e60 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
32e70 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
32e80 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
32e90 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
32ea0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
32eb0 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
32ec0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
32ed0 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
32ee0 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
32ef0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
32f00 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
32f10 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
32f20 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
32f30 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
32f40 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
32f50 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
32f60 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
32f70 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
32f80 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
32f90 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
32fa0 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
32fb0 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
32fc0 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
32fd0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
32fe0 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
32ff0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
33000 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
33010 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
33020 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
33030 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
33040 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
33050 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
33060 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
33070 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
33080 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  L    <td>   BLOB
33090 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
330a0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
330b0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
330c0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
330d0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
330e0 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
330f0 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
33100 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
33110 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
33120 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
33130 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
33140 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
33150 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
33160 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
33170 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
33180 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
33190 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
331a0 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
331b0 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
331c0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
331d0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
331e0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
331f0 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
33200 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
33210 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
33220 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  B    <td> [CAST]
33230 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e   to BLOB.** <tr>
33240 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
33250 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
33260 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
33270 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
33280 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
33290 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41  LOAT    <td> [CA
332a0 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c  ST] to REAL.** <
332b0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
332c0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
332d0 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
332e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
332f0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
33300 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
33310 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
33320 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
33330 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
33340 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
33350 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  L.** <tr><td>  B
33360 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
33370 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
33380 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
33390 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
333a0 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
333b0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
333c0 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
333d0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
333e0 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
333f0 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
33400 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
33410 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
33420 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
33430 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
33440 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
33450 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
33460 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
33470 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72  ..** Type conver
33480 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
33490 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
334a0 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
334b0 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
334c0 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
334d0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
334e0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
334f0 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
33500 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
33510 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
33520 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
33530 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
33540 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
33550 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
33560 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
33570 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
33580 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
33590 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
335a0 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
335b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
335c0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
335d0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
335e0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
335f0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
33600 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
33610 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
33620 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
33630 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
33640 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
33650 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
33660 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33670 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
33680 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
33690 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
336a0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
336b0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
336c0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
336d0 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
336e0 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72  l>.**.** ^Conver
336f0 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
33700 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
33710 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
33720 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
33730 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
33740 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
33750 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
33760 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
33770 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
33780 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
33790 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65  ior pointer refe
337a0 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65  rences will have
337b0 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
337c0 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
337d0 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
337e0 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
337f0 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
33800 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
33810 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
33820 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
33830 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
33840 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
33850 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
33860 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
33870 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
33880 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
33890 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
338a0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
338b0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
338c0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
338d0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
338e0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
338f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
33900 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
33910 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
33920 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
33930 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
33940 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
33950 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
33960 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
33970 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
33980 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
33990 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
339a0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
339b0 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
339c0 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
339d0 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
339e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
339f0 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
33a00 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
33a10 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
33a20 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
33a30 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
33a40 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
33a50 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
33a60 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
33a70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
33a80 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
33a90 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
33aa0 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
33ab0 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
33ac0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33ad0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
33ae0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
33af0 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
33b00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33b10 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
33b20 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
33b30 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
33b40 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
33b50 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
33b60 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
33b70 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f  )..**.** ^The po
33b80 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
33b90 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
33ba0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
33bb0 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
33bc0 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
33bd0 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
33be0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
33bf0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
33c00 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
33c10 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
33c20 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72  led.  ^The memor
33c30 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
33c40 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
33c50 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
33c60 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
33c70 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65  .  Do <em>not</e
33c80 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  m> pass the poin
33c90 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
33ca0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
33cb0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
33cc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33cd0 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
33ce0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
33cf0 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
33d00 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
33d10 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
33d20 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
33d30 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
33d40 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
33d50 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
33d60 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
33d70 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
33d80 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
33d90 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
33da0 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
33db0 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
33dc0 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
33dd0 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
33de0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
33df0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
33e00 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
33e10 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
33e20 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
33e30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33e40 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
33e50 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
33e60 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
33e70 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
33e80 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
33e90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
33ea0 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
33eb0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
33ec0 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  Col);.double sql
33ed0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
33ee0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
33ef0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
33f00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33f10 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
33f20 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
33f30 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
33f40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
33f50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33f60 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
33f70 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
33f80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33f90 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
33fa0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
33fb0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
33fc0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
33fd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
33fe0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
33ff0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
34000 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
34010 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
34020 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
34030 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
34040 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
34050 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
34060 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
34070 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
34080 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
34090 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71  * DESTRUCTOR: sq
340a0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
340b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
340c0 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
340d0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
340e0 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
340f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
34100 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
34110 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
34120 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
34130 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20   encountered no 
34140 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20  errors.** or if 
34150 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
34160 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c   never been eval
34170 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69  uated, then sqli
34180 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72  te3_finalize() r
34190 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45  eturns.** SQLITE
341a0 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  _OK.  ^If the mo
341b0 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
341c0 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e  tion of statemen
341d0 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  t S failed, then
341e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  .** sqlite3_fina
341f0 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20  lize(S) returns 
34200 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
34210 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a  [error code] or.
34220 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  ** [extended err
34230 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
34240 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
34250 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65  alize(S) routine
34260 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
34270 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
34280 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63  ng.** the life c
34290 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65  ycle of [prepare
342a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a  d statement] S:.
342b0 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d  ** before statem
342c0 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76  ent S is ever ev
342d0 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a  aluated, after.*
342e0 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61  * one or more ca
342f0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
34300 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74  reset()], or aft
34310 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74  er any call.** t
34320 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
34330 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  )] regardless of
34340 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
34350 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
34360 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  s.** completed e
34370 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  xecution..**.** 
34380 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65  ^Invoking sqlite
34390 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20  3_finalize() on 
343a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
343b0 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
343c0 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  op..**.** The ap
343d0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66  plication must f
343e0 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70  inalize every [p
343f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34400 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61  t] in order to a
34410 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65  void.** resource
34420 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61   leaks.  It is a
34430 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20   grievous error 
34440 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
34450 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73  ion to try to us
34460 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20  e.** a prepared 
34470 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
34480 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
34490 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20  lized.  Any use 
344a0 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  of a prepared.**
344b0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
344c0 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
344d0 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c  alized can resul
344e0 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  t in undefined a
344f0 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  nd.** undesirabl
34500 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20  e behavior such 
34510 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64  as segfaults and
34520 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e   heap corruption
34530 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
34540 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
34550 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
34560 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34570 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
34580 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
34590 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ct.** METHOD: sq
345a0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
345b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
345c0 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
345d0 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
345e0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
345f0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
34600 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
34610 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
34620 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
34630 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
34640 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
34650 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
34660 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
34670 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
34680 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
34690 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
346a0 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
346b0 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
346c0 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
346d0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
346e0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
346f0 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
34700 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
34710 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
34720 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
34730 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34740 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
34750 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
34760 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
34770 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
34780 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
34790 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
347a0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
347b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
347c0 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
347d0 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
347e0 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
347f0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
34800 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
34810 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
34820 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
34830 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34840 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
34850 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
34860 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
34870 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
34880 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
34890 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
348a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
348b0 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
348c0 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
348d0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
348e0 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
348f0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
34900 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
34910 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
34920 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
34930 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
34940 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
34950 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
34960 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
34970 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
34980 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
34990 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
349a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
349b0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
349c0 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
349d0 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
349e0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
349f0 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
34a00 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
34a10 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
34a20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
34a30 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
34a40 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
34a50 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
34a60 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
34a70 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ns}.** METHOD: s
34a80 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
34a90 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
34aa0 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
34ab0 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
34ac0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
34ad0 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
34ae0 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
34af0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
34b00 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
34b10 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
34b20 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
34b30 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
34b40 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
34b50 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
34b60 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
34b70 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
34b80 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
34b90 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
34ba0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
34bb0 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
34bc0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
34bd0 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
34be0 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
34bf0 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
34c00 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
34c10 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
34c20 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
34c30 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
34c40 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
34c50 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
34c60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34c70 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
34c80 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
34c90 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
34ca0 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
34cb0 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
34cc0 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
34cd0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
34ce0 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
34cf0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
34d00 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
34d10 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
34d20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34d30 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
34d40 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
34d50 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
34d60 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
34d70 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
34d80 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
34d90 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
34da0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
34db0 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
34dc0 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
34dd0 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
34de0 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
34df0 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
34e00 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
34e10 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
34e20 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
34e30 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
34e40 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
34e50 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
34e60 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
34e70 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
34e80 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
34e90 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
34ea0 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
34eb0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
34ec0 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
34ed0 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
34ee0 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
34ef0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
34f00 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
34f10 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
34f20 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
34f30 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
34f40 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
34f50 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
34f60 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
34f70 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
34f80 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
34f90 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
34fa0 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
34fb0 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
34fc0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
34fd0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
34fe0 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
34ff0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
35000 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
35010 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
35020 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
35030 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
35040 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
35050 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
35060 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
35070 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
35080 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
35090 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
350a0 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
350b0 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
350c0 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
350d0 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c  eters.  The appl
350e0 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73  ication should s
350f0 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  et this paramete
35100 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r to.** [SQLITE_
35110 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20  UTF16LE] if the 
35120 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
35130 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  ntation invokes 
35140 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
35150 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f  ue_text16le()] o
35160 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b  n an input, or [
35170 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20  SQLITE_UTF16BE] 
35180 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  if the.** implem
35190 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
351a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
351b0 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61  text16be()] on a
351c0 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b  n input, or.** [
351d0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66  SQLITE_UTF16] if
351e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
351f0 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 65  text16()] is use
35200 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  d, or [SQLITE_UT
35210 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  F8].** otherwise
35220 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c  .  ^The same SQL
35230 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
35240 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74   registered mult
35250 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67  iple times using
35260 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72  .** different pr
35270 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
35280 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66  odings, with dif
35290 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  ferent implement
352a0 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61  ations for.** ea
352b0 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20  ch encoding..** 
352c0 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
352d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
352e0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
352f0 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
35300 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
35310 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
35320 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
35330 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
35340 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
35350 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
35360 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61  rth parameter ma
35370 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20  y optionally be 
35380 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  ORed with [SQLIT
35390 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d  E_DETERMINISTIC]
353a0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68  .** to signal th
353b0 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  at the function 
353c0 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75  will always retu
353d0 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 75  rn the same resu
353e0 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20  lt given.** the 
353f0 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68  same inputs with
35400 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  in a single SQL 
35410 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74  statement.  Most
35420 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
35430 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73  re.** determinis
35440 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d  tic.  The built-
35450 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51  in [random()] SQ
35460 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e  L function is an
35470 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a   example of a.**
35480 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69   function that i
35490 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73  s not determinis
354a0 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65  tic.  The SQLite
354b0 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69   query planner i
354c0 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72  s able to.** per
354d0 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20  form additional 
354e0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e  optimizations on
354f0 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66   deterministic f
35500 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65  unctions, so use
35510 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
35520 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
35530 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d  ] flag is recomm
35540 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 73  ended where poss
35550 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ible..**.** ^(Th
35560 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
35570 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
35580 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
35590 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
355a0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
355b0 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
355c0 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
355d0 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  r using [sqlite3
355e0 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e  _user_data()].)^
355f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
35600 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65  h, seventh and e
35610 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73  ighth parameters
35620 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
35630 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
35640 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
35650 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
35660 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
35670 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
35680 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
35690 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51  te. ^A scalar SQ
356a0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
356b0 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
356c0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
356d0 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
356e0 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly; NULL pointe
356f0 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  rs must be passe
35700 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61  d as the xStep a
35710 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72  nd xFinal.** par
35720 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67  ameters. ^An agg
35730 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
35740 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
35750 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
35760 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  f xStep.** and x
35770 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70  Final and NULL p
35780 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70  ointer must be p
35790 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
357a0 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65   ^To delete an e
357b0 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
357c0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
357d0 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
357e0 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c  pointers for all
357f0 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
35800 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  ** callbacks..**
35810 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e  .** ^(If the nin
35820 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
35830 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
35840 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20  unction_v2() is 
35850 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65  not NULL,.** the
35860 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74  n it is destruct
35870 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
35880 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
35890 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73  ter. .** The des
358a0 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b  tructor is invok
358b0 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63  ed when the func
358c0 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c  tion is deleted,
358d0 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67   either by being
358e0 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f  .** overloaded o
358f0 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  r when the datab
35900 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
35910 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65  loses.)^.** ^The
35920 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61   destructor is a
35930 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74  lso invoked if t
35940 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  he call to.** sq
35950 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
35960 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73  ction_v2() fails
35970 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64  ..** ^When the d
35980 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
35990 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20  ck of the tenth 
359a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76  parameter is inv
359b0 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70  oked, it.** is p
359c0 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61  assed a single a
359d0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
359e0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61   a copy of the a
359f0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
35a00 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  .** pointer whic
35a10 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20  h was the fifth 
35a20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
35a30 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
35a40 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  tion_v2()..**.**
35a50 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65   ^It is permitte
35a60 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
35a70 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
35a80 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
35a90 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
35aa0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
35ab0 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
35ac0 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
35ad0 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
35ae0 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
35af0 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
35b00 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51   encodings.  ^SQ
35b10 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
35b20 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
35b30 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c  ion that most cl
35b40 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
35b50 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
35b60 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
35b70 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20  on is used.  ^A 
35b80 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
35b90 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
35ba0 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e  on-negative.** n
35bb0 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  Arg parameter is
35bc0 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
35bd0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
35be0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
35bf0 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76  ith.** a negativ
35c00 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63  e nArg.  ^A func
35c10 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70  tion where the p
35c20 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
35c30 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65  coding.** matche
35c40 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
35c50 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74  ncoding is a bet
35c60 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61  ter.** match tha
35c70 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
35c80 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
35c90 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a  is different.  .
35ca0 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  ** ^A function w
35cb0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
35cc0 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20  g difference is 
35cd0 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20  between UTF16le 
35ce0 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69  and UTF16be.** i
35cf0 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68  s a closer match
35d00 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
35d10 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
35d20 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
35d30 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46  s.** between UTF
35d40 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a  8 and UTF16..**.
35d50 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e  ** ^Built-in fun
35d60 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
35d70 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
35d80 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
35d90 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
35da0 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61  *.** ^An applica
35db0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
35dc0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
35dd0 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
35de0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
35df0 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
35e00 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
35e10 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
35e20 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
35e30 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
35e40 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
35e50 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
35e60 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
35e70 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
35e80 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73  unning..*/.int s
35e90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35ea0 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
35eb0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
35ec0 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
35ed0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
35ee0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
35ef0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
35f00 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
35f10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
35f20 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
35f30 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
35f40 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
35f50 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
35f60 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
35f70 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
35f80 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
35f90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
35fa0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
35fb0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
35fc0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
35fd0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
35fe0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
35ff0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
36000 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
36010 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
36020 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
36030 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
36040 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
36050 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
36060 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
36070 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
36080 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
36090 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
360a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
360b0 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  nction_v2(.  sql
360c0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
360d0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
360e0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
360f0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
36100 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
36110 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
36120 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36130 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
36140 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
36150 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
36160 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
36170 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
36180 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
36190 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
361a0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
361b0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a  roy)(void*).);..
361c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
361d0 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a  Text Encodings.*
361e0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
361f0 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67  ant define integ
36200 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65  er codes that re
36210 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69  present the vari
36220 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  ous.** text enco
36230 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20  dings supported 
36240 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  by SQLite..*/.#d
36250 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
36260 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20 20  8           1   
36270 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34   /* IMP: R-37514
36280 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e  -35566 */.#defin
36290 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
362a0 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20          2    /* 
362b0 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36  IMP: R-03371-376
362c0 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  37 */.#define SQ
362d0 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
362e0 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a      3    /* IMP:
362f0 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a   R-51971-34154 *
36300 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
36310 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
36320 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
36330 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
36340 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36350 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35  ANY            5
36360 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65      /* Deprecate
36370 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
36380 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
36390 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
363a0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
363b0 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
363c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
363d0 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a  ction Flags.**.*
363e0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
363f0 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f  s may be ORed to
36400 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65 20  gether with the 
36410 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
36420 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65 78   | preferred tex
36430 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74  t encoding] as t
36440 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
36450 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  nt.** to [sqlite
36460 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
36470 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
36480 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
36490 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
364a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
364b0 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64  ion_v2()]..*/.#d
364c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
364d0 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78  ERMINISTIC    0x
364e0 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  800../*.** CAPI3
364f0 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
36500 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
36510 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
36520 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
36530 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
36540 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
36550 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
36560 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
36570 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
36580 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
36590 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
365a0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
365b0 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
365c0 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
365d0 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
365e0 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
365f0 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75  tions.  To encou
36600 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72 73  rage programmers
36610 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65   to avoid.** the
36620 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65  se functions, we
36630 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69   will not explai
36640 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a  n what they do..
36650 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
36660 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45  E_OMIT_DEPRECATE
36670 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  D.SQLITE_DEPRECA
36680 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
36690 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
366a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
366b0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
366c0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
366d0 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
366e0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
366f0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
36700 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
36710 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
36720 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
36730 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
36740 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
36750 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
36760 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
36770 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
36780 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  id sqlite3_threa
36790 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b  d_cleanup(void);
367a0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
367b0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
367c0 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
367d0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
367e0 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20  3_int64,int),.  
367f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36800 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65      void*,sqlite
36810 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66  3_int64);.#endif
36820 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36830 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20  : Obtaining SQL 
36840 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  Values.** METHOD
36850 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a  : sqlite3_value.
36860 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
36870 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
36880 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
36890 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
368a0 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
368b0 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
368c0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
368d0 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
368e0 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
368f0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
36900 61 67 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a  aggregate.  .**.
36910 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
36920 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
36930 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
36940 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
36950 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
36960 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
36970 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
36980 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
36990 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
369a0 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
369b0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
369c0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
369d0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
369e0 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72  ..** The 3rd par
369f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
36a00 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
36a10 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36a20 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
36a30 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
36a40 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
36a50 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
36a60 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
36a70 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
36a80 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
36a90 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
36aa0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
36ab0 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
36ac0 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
36ad0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
36ae0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
36af0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
36b00 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
36b10 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
36b20 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
36b30 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
36b40 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
36b50 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
36b60 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
36b70 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
36b80 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
36b90 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
36ba0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
36bb0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
36bc0 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
36bd0 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
36be0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
36bf0 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
36c00 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  t these routines
36c10 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
36c20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
36c30 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
36c40 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
36c50 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
36c60 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
36c70 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
36c80 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
36c90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36ca0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
36cb0 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
36cc0 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
36cd0 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
36ce0 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
36cf0 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
36d00 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ne.  ^The.** sql
36d10 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
36d20 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
36d30 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
36d40 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
36d50 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
36d60 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
36d70 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
36d80 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
36d90 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  vely..**.** ^If 
36da0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
36db0 6f 62 6a 65 63 74 20 56 20 77 61 73 20 69 6e 69  object V was ini
36dc0 74 69 61 6c 69 7a 65 64 20 0a 2a 2a 20 75 73 69  tialized .** usi
36dd0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ng [sqlite3_bind
36de0 5f 70 6f 69 6e 74 65 72 28 53 2c 49 2c 50 29 5d  _pointer(S,I,P)]
36df0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
36e00 75 6c 74 5f 70 6f 69 6e 74 65 72 28 43 2c 50 29  ult_pointer(C,P)
36e10 5d 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  ], then.** sqlit
36e20 65 33 5f 76 61 6c 75 65 5f 70 6f 69 6e 74 65 72  e3_value_pointer
36e30 28 56 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  (V) will return 
36e40 74 68 65 20 70 6f 69 6e 74 65 72 20 50 2e 20 20  the pointer P.  
36e50 4f 74 68 65 72 77 69 73 65 2c 0a 2a 2a 20 73 71  Otherwise,.** sq
36e60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 70 6f 69 6e  lite3_value_poin
36e70 74 65 72 28 56 29 20 72 65 74 75 72 6e 73 20 61  ter(V) returns a
36e80 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   NULL..**.** ^(T
36e90 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
36ea0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
36eb0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
36ec0 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
36ed0 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
36ee0 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
36ef0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
36f00 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
36f10 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
36f20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
36f30 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
36f40 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
36f50 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
36f60 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
36f70 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
36f80 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
36f90 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
36fa0 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
36fb0 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
36fc0 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
36fd0 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
36fe0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
36ff0 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
37000 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
37010 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
37020 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
37030 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
37040 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
37050 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
37060 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
37070 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
37080 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
37090 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
370a0 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
370b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
370c0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
370d0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
370e0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
370f0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
37100 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
37110 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
37120 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
37130 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
37140 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
37150 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
37160 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
37170 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
37180 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37190 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
371a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
371b0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
371c0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
371d0 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
371e0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
371f0 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
37200 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
37210 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  meters..*/.const
37220 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
37230 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
37240 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
37250 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
37260 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
37270 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
37280 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
37290 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
372a0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
372b0 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
372c0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
372d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
372e0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
372f0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
37300 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
37310 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
37320 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
37330 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
37340 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
37350 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
37360 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
37370 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
37380 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37390 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
373a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
373b0 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
373c0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
373d0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
373e0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
373f0 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 2a 73  value*);.void *s
37400 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 70 6f 69  qlite3_value_poi
37410 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 76 61 6c  nter(sqlite3_val
37420 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
37430 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
37440 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
37450 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
37460 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
37470 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
37480 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
37490 69 6e 64 69 6e 67 20 54 68 65 20 53 75 62 74 79  inding The Subty
374a0 70 65 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 73  pe Of SQL Values
374b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
374c0 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20  te3_value.**.** 
374d0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
374e0 65 5f 73 75 62 74 79 70 65 28 56 29 20 66 75 6e  e_subtype(V) fun
374f0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
37500 65 20 73 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a  e subtype for.**
37510 20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   an [application
37520 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
37530 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20  ction] argument 
37540 56 2e 20 20 54 68 65 20 73 75 62 74 79 70 65 0a  V.  The subtype.
37550 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63  ** information c
37560 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 70 61  an be used to pa
37570 73 73 20 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f  ss a limited amo
37580 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 66  unt of context f
37590 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66  rom.** one SQL f
375a0 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68  unction to anoth
375b0 65 72 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71  er.  Use the [sq
375c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62  lite3_result_sub
375d0 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  type()].** routi
375e0 6e 65 20 74 6f 20 73 65 74 20 74 68 65 20 73 75  ne to set the su
375f0 62 74 79 70 65 20 66 6f 72 20 74 68 65 20 72 65  btype for the re
37600 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e  turn value of an
37610 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
37620 2f 0a 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73  /.unsigned int s
37630 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62  qlite3_value_sub
37640 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
37650 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
37660 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 20  I3REF: Copy And 
37670 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65 73 0a  Free SQL Values.
37680 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
37690 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e  e3_value.**.** ^
376a0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
376b0 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61  e_dup(V) interfa
376c0 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
376d0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
376e0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
376f0 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61   D and returns a
37700 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
37710 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 71   copy.  ^The [sq
37720 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 74  lite3_value] ret
37730 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70  urned.** is a [p
37740 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
37750 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65  _value] object e
37760 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70 75 74  ven if the input
37770 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65   is not..** ^The
37780 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
37790 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20  up(V) interface 
377a0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
377b0 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20  V is NULL or if 
377c0 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
377d0 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a  cation fails..**
377e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
377f0 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69  _value_free(V) i
37800 6e 74 65 72 66 61 63 65 20 66 72 65 65 73 20 61  nterface frees a
37810 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  n [sqlite3_value
37820 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76  ] object.** prev
37830 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
37840 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
37850 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66  lue_dup()].  ^If
37860 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   V is a NULL poi
37870 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  nter.** then sql
37880 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28  ite3_value_free(
37890 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  V) is a harmless
378a0 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 73 71 6c 69 74   no-op..*/.sqlit
378b0 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
378c0 33 5f 76 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73  3_value_dup(cons
378d0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
378e0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
378f0 76 61 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 74  value_free(sqlit
37900 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
37910 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
37920 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
37930 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
37940 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
37950 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  3_context.**.** 
37960 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  Implementations 
37970 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
37980 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
37990 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
379a0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
379b0 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
379c0 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
379d0 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
379e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
379f0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
37a00 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
37a10 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
37a20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
37a30 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
37a40 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
37a50 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
37a60 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
37a70 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
37a80 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
37a90 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
37aa0 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
37ab0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
37ac0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
37ad0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
37ae0 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
37af0 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
37b00 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
37b10 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
37b20 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
37b30 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
37b40 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
37b50 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
37b60 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
37b70 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
37b80 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
37b90 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
37ba0 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
37bb0 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
37bc0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
37bd0 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
37be0 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
37bf0 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
37c00 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
37c10 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
37c20 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
37c30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
37c40 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
37c50 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
37c60 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
37c70 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
37c80 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
37c90 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
37ca0 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
37cb0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
37cc0 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
37cd0 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
37ce0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37cf0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
37d00 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
37d10 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
37d20 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68  L pointer .** wh
37d30 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20  en first called 
37d40 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  if N is less tha
37d50 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
37d60 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  ro or if a memor
37d70 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72  y.** allocate er
37d80 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
37d90 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f  * ^(The amount o
37da0 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65  f space allocate
37db0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67  d by sqlite3_agg
37dc0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
37dd0 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d  ,N) is.** determ
37de0 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61  ined by the N pa
37df0 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74  rameter on first
37e00 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
37e10 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a  .  Changing the.
37e20 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e  ** value of N in
37e30 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
37e40 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
37e50 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
37e60 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61  within.** the sa
37e70 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
37e80 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77  ction instance w
37e90 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74  ill not resize t
37ea0 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
37eb0 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68  ocation.)^  With
37ec0 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  in the xFinal ca
37ed0 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75  llback, it is cu
37ee0 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a  stomary to set.*
37ef0 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74  * N=0 in calls t
37f00 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
37f10 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
37f20 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20   so that no .** 
37f30 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79  pointless memory
37f40 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63   allocations occ
37f50 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ur..**.** ^SQLit
37f60 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
37f70 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
37f80 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
37f90 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
37fa0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
37fb0 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
37fc0 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
37fd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
37fe0 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
37ff0 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
38000 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
38010 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
38020 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
38030 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
38040 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
38050 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
38060 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
38070 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
38080 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
38090 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
380a0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
380b0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
380c0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
380d0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
380e0 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
380f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
38100 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
38110 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
38120 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
38130 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
38140 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
38150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
38160 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
38170 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
38180 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
38190 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
381a0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
381b0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
381c0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
381d0 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
381e0 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
381f0 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
38200 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
38210 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
38220 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
38230 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
38240 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
38250 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
38260 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
38270 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
38280 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
38290 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
382a0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
382b0 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
382c0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
382d0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
382e0 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
382f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
38300 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
38310 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
38320 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
38330 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
38340 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38350 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
38360 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
38370 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
38380 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
38390 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
383a0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
383b0 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
383c0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
383d0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
383e0 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
383f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
38400 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
38410 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
38420 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
38430 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
38440 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
38450 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
38460 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
38470 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
38480 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
38490 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
384a0 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  tion..*/.sqlite3
384b0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
384c0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
384d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
384e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
384f0 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
38500 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f  ry Data.** METHO
38510 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  D: sqlite3_conte
38520 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  xt.**.** These f
38530 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
38540 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67  used by (non-agg
38550 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63  regate) SQL func
38560 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
38570 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
38580 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
38590 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
385a0 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
385b0 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
385c0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
385d0 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
385e0 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
385f0 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
38600 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
38610 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
38620 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
38630 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
38640 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a  d.  An example.*
38650 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20  * of where this 
38660 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20  might be useful 
38670 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d  is in a regular-
38680 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
38690 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ing.** function.
386a0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
386b0 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
386c0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
386d0 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73  can be stored as
386e0 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73  .** metadata ass
386f0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
38700 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e   pattern string.
38710 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f    .** Then as lo
38720 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 65 72  ng as the patter
38730 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73  n string remains
38740 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68   the same,.** th
38750 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
38760 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
38770 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
38780 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
38790 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
387a0 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  me function..**.
387b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
387c0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
387d0 74 65 72 66 61