System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 14a7b1694f0a156e9b71acb9952e66608f9865f2:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65  LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e  ** Since version
0f00: 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20   3.6.18, SQLite 
0f10: 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73 20  source code has 
0f20: 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74  been stored in t
0f30: 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68  he.** <a href="h
0f40: 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c  ttp://www.fossil
0f50: 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69  -scm.org/">Fossi
0f60: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  l configuration 
0f70: 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79  management.** sy
0f80: 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20  stem</a>.  ^The 
0f90: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
0fa0: 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73   macro evaluates
0fb0: 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20   to.** a string 
0fc0: 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65 73  which identifies
0fd0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 68   a particular ch
0fe0: 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65  eck-in of SQLite
0ff0: 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63  .** within its c
1000: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e  onfiguration man
1010: 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20  agement system. 
1020: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55   ^The SQLITE_SOU
1030: 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67  RCE_ID.** string
1040: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
1050: 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74  te and time of t
1060: 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43  he check-in (UTC
1070: 29 20 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a  ) and an SHA1.**
1080: 20 68 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74   hash of the ent
1090: 69 72 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ire source tree.
10a0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
10b0: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
10c0: 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sion()],.** [sql
10d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
10e0: 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69  number()], [sqli
10f0: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c  te3_sourceid()],
1100: 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73  .** [sqlite_vers
1110: 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
1120: 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e  te_source_id()].
1130: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1140: 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20  TE_VERSION      
1150: 20 20 22 33 2e 31 34 2e 30 22 0a 23 64 65 66 69    "3.14.0".#defi
1160: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
1170: 4e 5f 4e 55 4d 42 45 52 20 33 30 31 34 30 30 30  N_NUMBER 3014000
1180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1190: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
11a0: 32 30 31 36 2d 30 37 2d 32 39 20 31 37 3a 33 36  2016-07-29 17:36
11b0: 3a 32 37 20 39 66 61 65 37 35 63 30 38 62 37 64  :27 9fae75c08b7d
11c0: 33 62 33 65 31 33 37 33 34 31 39 33 61 64 38 33  3b3e13734193ad83
11d0: 39 38 65 66 36 39 37 31 63 62 61 63 22 0a 0a 2f  98ef6971cbac"../
11e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
11f0: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1200: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
1210: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
1220: 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71  ite3_version, sq
1230: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a  lite3_sourceid.*
1240: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72  *.** These inter
1250: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68  faces provide th
1260: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
1270: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54  on as the [SQLIT
1280: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b  E_VERSION],.** [
1290: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
12a0: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c  UMBER], and [SQL
12b0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
12c0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
12d0: 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20  cros.** but are 
12e0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
12f0: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
1300: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
1310: 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69  r file.  ^(Cauti
1320: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65  ous.** programme
1330: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65  rs might include
1340: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
1350: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70  ents in their ap
1360: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
1370: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75  verify that valu
1380: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  es returned by t
1390: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
13a0: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73  match the macros
13b0: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65   in.** the heade
13c0: 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75  r, and thus ensu
13d0: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c  re that the appl
13e0: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f  ication is.** co
13f0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63  mpiled with matc
1400: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64  hing library and
1410: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a   header files..*
1420: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1430: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74  ><pre>.** assert
1440: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  ( sqlite3_libver
1450: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53  sion_number()==S
1460: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1470: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72  MBER );.** asser
1480: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1490: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
14a0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d  ITE_SOURCE_ID)==
14b0: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20  0 );.** assert( 
14c0: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c  strcmp(sqlite3_l
14d0: 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49  ibversion(),SQLI
14e0: 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29  TE_VERSION)==0 )
14f0: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1500: 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1510: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65   ^The sqlite3_ve
1520: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
1530: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73  onstant contains
1540: 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51   the text of [SQ
1550: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a  LITE_VERSION].**
1560: 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71   macro.  ^The sq
1570: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1580: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
1590: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
15a0: 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73   the.** to the s
15b0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
15c0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
15d0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  .  The sqlite3_l
15e0: 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66  ibversion().** f
15f0: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
1600: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44  ded for use in D
1610: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73  LLs since DLL us
1620: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e  ers usually do n
1630: 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63  ot have.** direc
1640: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
1650: 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74  ng constants wit
1660: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54  hin the DLL.  ^T
1670: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  he.** sqlite3_li
1680: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1690: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
16a0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71  ns an integer eq
16b0: 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ual to.** [SQLIT
16c0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
16d0: 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
16e0: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63  _sourceid() func
16f0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a  tion returns .**
1700: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1710: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
1720: 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74  whose value is t
1730: 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a  he same as the .
1740: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  ** [SQLITE_SOURC
1750: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
1760: 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  ssor macro..**.*
1770: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1780: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
1790: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
17a0: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  e_id()]..*/.SQLI
17b0: 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58  TE_API SQLITE_EX
17c0: 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20  TERN const char 
17d0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
17e0: 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  ];.SQLITE_API co
17f0: 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
1800: 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33  _APICALL sqlite3
1810: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64  _libversion(void
1820: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
1830: 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
1840: 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33  _APICALL sqlite3
1850: 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b  _sourceid(void);
1860: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1870: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73  SQLITE_APICALL s
1880: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1890: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
18a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18b0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
18c0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
18d0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
18e0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
18f0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1900: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
1910: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1920: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1930: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1940: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1950: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1960: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1970: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1980: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1990: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
19a0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
19b0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
19c0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
19d0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
19e0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
19f0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1a00: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1a10: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1a20: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1a30: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1a40: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1a50: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1a60: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1a70: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1a80: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1a90: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1aa0: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1ab0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ac0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1ad0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1ae0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1af0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1b00: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1b10: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1b20: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1b30: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1b40: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1b50: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1b60: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1b70: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1b80: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1b90: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1ba0: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1bb0: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1bc0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1bd0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1be0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1bf0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1c00: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1c10: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1c20: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1c30: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1c40: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1c50: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1c60: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1c70: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1c80: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1c90: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1ca0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1cb0: 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  GS.SQLITE_API in
1cc0: 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c  t SQLITE_APICALL
1cd0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ce0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73  option_used(cons
1cf0: 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65  t char *zOptName
1d00: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
1d10: 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
1d20: 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33  _APICALL sqlite3
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69  et(int N);.#endi
1d50: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
1d60: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  F: Test To See I
1d70: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73  f The Library Is
1d80: 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a   Threadsafe.**.*
1d90: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1da0: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
1db0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72  tion returns zer
1dc0: 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  o if and only if
1dd0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63  .** SQLite was c
1de0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74  ompiled with mut
1df0: 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74  exing code omitt
1e00: 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a  ed due to the.**
1e10: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1e20: 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AFE] compile-tim
1e30: 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73  e option being s
1e40: 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53  et to 0..**.** S
1e50: 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d  QLite can be com
1e60: 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69  piled with or wi
1e70: 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20  thout mutexes.  
1e80: 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  When.** the [SQL
1e90: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1ea0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1eb0: 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20  acro is 1 or 2, 
1ec0: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
1ed0: 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74  nabled and SQLit
1ee0: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e  e is threadsafe.
1ef0: 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53    When the.** [S
1f00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1f10: 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a  ] macro is 0, .*
1f20: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72  * the mutexes ar
1f30: 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68  e omitted.  With
1f40: 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c  out the mutexes,
1f50: 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a   it is not safe.
1f60: 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65  ** to use SQLite
1f70: 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72   concurrently fr
1f80: 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  om more than one
1f90: 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45   thread..**.** E
1fa0: 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20  nabling mutexes 
1fb0: 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61  incurs a measura
1fc0: 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ble performance 
1fd0: 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69  penalty..** So i
1fe0: 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74  f speed is of ut
1ff0: 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c  most importance,
2000: 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20   it makes sense 
2010: 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  to disable.** th
2020: 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20  e mutexes.  But 
2030: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65  for maximum safe
2040: 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75  ty, mutexes shou
2050: 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  ld be enabled..*
2060: 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
2070: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
2080: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
2090: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
20a0: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
20b0: 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70  e used by an app
20c0: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65  lication to make
20d0: 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a   sure that the.*
20e0: 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  * version of SQL
20f0: 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c  ite that it is l
2100: 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77  inking against w
2110: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
2120: 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20  .** the desired 
2130: 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b  setting of the [
2140: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
2150: 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  E] macro..**.** 
2160: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f  This interface o
2170: 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74  nly reports on t
2180: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
2190: 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a  mutex setting.**
21a0: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
21b0: 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67  THREADSAFE] flag
21c0: 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
21d0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
21e0: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
21f0: 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20  FE=1 or =2 then 
2200: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62  mutexes are enab
2210: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62  led by default b
2220: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c  ut.** can be ful
2230: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20  ly or partially 
2240: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61  disabled using a
2250: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2260: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77  3_config()].** w
2270: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53  ith the verbs [S
2280: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
2290: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c  GLETHREAD], [SQL
22a0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
22b0: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b  THREAD],.** or [
22c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
22d0: 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68  RIALIZED].  ^(Th
22e0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
22f0: 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  f the.** sqlite3
2300: 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75  _threadsafe() fu
2310: 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c  nction shows onl
2320: 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  y the compile-ti
2330: 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a  me setting of.**
2340: 20 74 68 72 65 61 64 20 73 61 66 65 74 79 2c 20   thread safety, 
2350: 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65  not any run-time
2360: 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74   changes to that
2370: 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79   setting made by
2380: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  .** sqlite3_conf
2390: 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77  ig(). In other w
23a0: 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e  ords, the return
23b0: 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
23c0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
23d0: 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64  .** is unchanged
23e0: 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c   by calls to sql
23f0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e  ite3_config().)^
2400: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b  .**.** See the [
2410: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
2420: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
2430: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
2440: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  ormation..*/.SQL
2450: 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2460: 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74  TE_APICALL sqlit
2470: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f  e3_threadsafe(vo
2480: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
2490: 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
24a0: 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65  onnection Handle
24b0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
24c0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24d0: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
24e0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
24f0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
2500: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
2510: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
2520: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
2530: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
2540: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
2550: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
2560: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
2570: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
2580: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
2590: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
25a0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
25b0: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
25c0: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
25d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
25e0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
25f0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
2600: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
2610: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
2620: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2630: 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73  se_v2()] are its
2640: 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54   destructors.  T
2650: 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74  here are many ot
2660: 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  her.** interface
2670: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
2680: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2690: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
26a0: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
26b0: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
26c0: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
26d0: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
26e0: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
26f0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
2700: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
2710: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2720: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
2730: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
2740: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2750: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2760: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2770: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2780: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
2790: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
27a0: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
27b0: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
27c0: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
27d0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
27e0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
27f0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
2800: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
2810: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
2820: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
2830: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
2840: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2850: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2860: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2870: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2880: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
2890: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
28a0: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
28b0: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
28c0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28d0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
28e0: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
28f0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
2900: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
2910: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
2920: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
2930: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2940: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2950: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2960: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2970: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2980: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2990: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
29a0: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
29b0: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
29c0: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
29d0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
29e0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
29f0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2a00: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
2a10: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2a20: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
2a30: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
2a40: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2a50: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2a60: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2a70: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2a80: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 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 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2ab0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2ac0: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
2ad0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2ae0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
2af0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
2b00: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2b10: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
2b20: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
2b30: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
2b40: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2b50: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2b60: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2b70: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2b80: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2b90: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2ba0: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2bb0: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2bc0: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
2bd0: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
2be0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
2bf0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
2c00: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
2c10: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
2c20: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2c30: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
2c40: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2c50: 63 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43  ction.** DESTRUC
2c60: 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  TOR: sqlite3.**.
2c70: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c80: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69  close() and sqli
2c90: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72  te3_close_v2() r
2ca0: 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 74  outines are dest
2cb0: 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74  ructors.** for t
2cc0: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2cd0: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ect..** ^Calls t
2ce0: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  o sqlite3_close(
2cf0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2d00: 6f 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20  ose_v2() return 
2d10: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a  [SQLITE_OK] if.*
2d20: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  * the [sqlite3] 
2d30: 6f 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73  object is succes
2d40: 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64  sfully destroyed
2d50: 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61   and all associa
2d60: 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73  ted.** resources
2d70: 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64   are deallocated
2d80: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2d90: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2da0: 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65  ion is associate
2db0: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2dc0: 65 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  ed prepared.** s
2dd0: 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66  tatements or unf
2de0: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f  inished sqlite3_
2df0: 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74  backup objects t
2e00: 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  hen sqlite3_clos
2e10: 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76  e().** will leav
2e20: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
2e30: 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61  onnection open a
2e40: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
2e50: 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20  E_BUSY]..** ^If 
2e60: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2e70: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
2e80: 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72  h unfinalized pr
2e90: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ea0: 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69  s.** and/or unfi
2eb0: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
2ec0: 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65  ackups, then the
2ed0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2ee0: 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20  tion becomes.** 
2ef0: 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d  an unusable "zom
2f00: 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20  bie" which will 
2f10: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65  automatically be
2f20: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65   deallocated whe
2f30: 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72  n the.** last pr
2f40: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f50: 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72   is finalized or
2f60: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
2f70: 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66  3_backup is.** f
2f80: 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71  inished.  The sq
2f90: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2fa0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e   interface is in
2fb0: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77  tended for use w
2fc0: 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67  ith.** host lang
2fd0: 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67  uages that are g
2fe0: 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64  arbage collected
2ff0: 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20  , and where the 
3000: 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a  order in which.*
3010: 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72  * destructors ar
3020: 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69  e called is arbi
3030: 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  trary..**.** App
3040: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
3050: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
3060: 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61  ze | finalize] a
3070: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
3080: 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71  tements],.** [sq
3090: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
30a0: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42   | close] all [B
30b0: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e  LOB handles], an
30c0: 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  d .** [sqlite3_b
30d0: 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66  ackup_finish | f
30e0: 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69  inish] all [sqli
30f0: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
3100: 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  cts associated.*
3110: 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69  * with the [sqli
3120: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f  te3] object prio
3130: 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20  r to attempting 
3140: 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a  to close the obj
3150: 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c  ect.  ^If.** sql
3160: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3170: 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  is called on a [
3180: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3190: 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20  ion] that still 
31a0: 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69  has.** outstandi
31b0: 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ng [prepared sta
31c0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
31d0: 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72  handles], and/or
31e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31f0: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65  kup] objects the
3200: 6e 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51  n it returns [SQ
3210: 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65  LITE_OK] and the
3220: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
3230: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
3240: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3250: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3260: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3270: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3280: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3290: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
32a0: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
32b0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
32c0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
32d0: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
32e0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
32f0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
3300: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
3310: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
3320: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
3330: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
3340: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3350: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3360: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3370: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3380: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3390: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
33a0: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
33b0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
33c0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
33d0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
33e0: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
33f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
3400: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
3410: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
3420: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
3430: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
3440: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3450: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3460: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3470: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3480: 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  -op..*/.SQLITE_A
3490: 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50  PI int SQLITE_AP
34a0: 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c  ICALL sqlite3_cl
34b0: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53  ose(sqlite3*);.S
34c0: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
34d0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c  LITE_APICALL sql
34e0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71  ite3_close_v2(sq
34f0: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
3500: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63  The type for a c
3510: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
3520: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67  ..** This is leg
3530: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74  acy and deprecat
3540: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75  ed.  It is inclu
3550: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ded for historic
3560: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  al.** compatibil
3570: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64  ity and is not d
3580: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79  ocumented..*/.ty
3590: 70 65 64 65 66 20 69 6e 74 20 28 53 51 4c 49 54  pedef int (SQLIT
35a0: 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 73 71 6c 69  E_CALLBACK *sqli
35b0: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f  te3_callback)(vo
35c0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20  id*,int,char**, 
35d0: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  char**);../*.** 
35e0: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74  CAPI3REF: One-St
35f0: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69  ep Query Executi
3600: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20  on Interface.** 
3610: 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
3620: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
3630: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
3640: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
3650: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
3660: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  nd.** [sqlite3_p
3670: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
3680: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
3690: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
36a0: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61  alize()],.** tha
36b0: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c  t allows an appl
36c0: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d  ication to run m
36d0: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e  ultiple statemen
36e0: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74  ts of SQL.** wit
36f0: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75  hout having to u
3700: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f  se a lot of C co
3710: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de. .**.** ^The 
3720: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3730: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65  nterface runs ze
3740: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38  ro or more UTF-8
3750: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d   encoded,.** sem
3760: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20  icolon-separate 
3770: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
3780: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32  assed into its 2
3790: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20  nd argument,.** 
37a0: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f  in the context o
37b0: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
37c0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73  connection] pass
37d0: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74  ed in as its 1st
37e0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  .** argument.  ^
37f0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3800: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20  function of the 
3810: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  3rd argument to.
3820: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3830: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  ) is not NULL, t
3840: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  hen it is invoke
3850: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c  d for each resul
3860: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20  t row.** coming 
3870: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75  out of the evalu
3880: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
3890: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61  nts.  ^The 4th a
38a0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
38b0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
38c0: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20  relayed through 
38d0: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d  to the 1st argum
38e0: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63  ent of each.** c
38f0: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69  allback invocati
3900: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  on.  ^If the cal
3910: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f  lback pointer to
3920: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3930: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ** is NULL, then
3940: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20   no callback is 
3950: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64  ever invoked and
3960: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65   result rows are
3970: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  .** ignored..**.
3980: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
3990: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61  occurs while eva
39a0: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20  luating the SQL 
39b0: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
39c0: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  d into.** sqlite
39d0: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65  3_exec(), then e
39e0: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
39f0: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e  current statemen
3a00: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73  t stops and.** s
3a10: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d  ubsequent statem
3a20: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64  ents are skipped
3a30: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  .  ^If the 5th p
3a40: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3a50: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3a60: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61   not NULL then a
3a70: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
3a80: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
3a90: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
3aa0: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3ab0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
3ac0: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
3ad0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3ae0: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f  meter..** To avo
3af0: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c  id memory leaks,
3b00: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
3b10: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b   should invoke [
3b20: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
3b30: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73  ** on error mess
3b40: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  age strings retu
3b50: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
3b60: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   5th parameter o
3b70: 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  f.** sqlite3_exe
3b80: 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72  c() after the er
3b90: 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
3ba0: 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ng is no longer 
3bb0: 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  needed..** ^If t
3bc0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3bd0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3be0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  () is not NULL a
3bf0: 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  nd no errors.** 
3c00: 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69  occur, then sqli
3c10: 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20  te3_exec() sets 
3c20: 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69  the pointer in i
3c30: 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  ts 5th parameter
3c40: 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f   to.** NULL befo
3c50: 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
3c60: 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74  .** ^If an sqlit
3c70: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3c80: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
3c90: 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ero, the sqlite3
3ca0: 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69  _exec().** routi
3cb0: 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  ne returns SQLIT
3cc0: 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20  E_ABORT without 
3cd0: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c  invoking the cal
3ce0: 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a  lback again and.
3cf0: 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69  ** without runni
3d00: 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  ng any subsequen
3d10: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
3d20: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64  ..**.** ^The 2nd
3d30: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3d40: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3d50: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3d60: 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  n is the.** numb
3d70: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
3d80: 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54   the result.  ^T
3d90: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
3da0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3db0: 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63  xec().** callbac
3dc0: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3dd0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3de0: 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73  ings obtained as
3df0: 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c   if from.** [sql
3e00: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
3e10: 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63  ()], one for eac
3e20: 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61  h column.  ^If a
3e30: 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a  n element of a.*
3e40: 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20  * result row is 
3e50: 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
3e60: 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69  rresponding stri
3e70: 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  ng pointer for t
3e80: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
3e90: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
3ea0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
3eb0: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d    ^The 4th argum
3ec0: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71  ent to the.** sq
3ed0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3ee0: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61  lback is an arra
3ef0: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3f00: 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65   strings where e
3f10: 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70  ach.** entry rep
3f20: 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65  resents the name
3f30: 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e   of correspondin
3f40: 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  g result column 
3f50: 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  as obtained.** f
3f60: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
3f70: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a  umn_name()]..**.
3f80: 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70  ** ^If the 2nd p
3f90: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3fa0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20  te3_exec() is a 
3fb0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20  NULL pointer, a 
3fc0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e  pointer.** to an
3fd0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f   empty string, o
3fe0: 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  r a pointer that
3ff0: 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77   contains only w
4000: 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72  hitespace and/or
4010: 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74   .** SQL comment
4020: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73  s, then no SQL s
4030: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76  tatements are ev
4040: 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20  aluated and the 
4050: 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e  database.** is n
4060: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a  ot changed..**.*
4070: 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a  * Restrictions:.
4080: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
4090: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
40a0: 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74  on must ensure t
40b0: 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61  hat the 1st para
40c0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
40d0: 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20  _exec().**      
40e0: 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f  is a valid and o
40f0: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
4100: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c  nnection]..** <l
4110: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
4120: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  on must not clos
4130: 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
4140: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
4150: 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
4160: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
4170: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4180: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
4190: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
41a0: 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ning..** <li> Th
41b0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
41c0: 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  st not modify th
41d0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
41e0: 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f  text passed into
41f0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64  .**      the 2nd
4200: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
4210: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
4220: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
4230: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
4240: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ul>.*/.SQLITE
4250: 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
4260: 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  APICALL sqlite3_
4270: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4280: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42a0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
42b0: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
42c0: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
42d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42e0: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
42f0: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4300: 0a 20 20 69 6e 74 20 28 53 51 4c 49 54 45 5f 43  .  int (SQLITE_C
4310: 41 4c 4c 42 41 43 4b 20 2a 63 61 6c 6c 62 61 63  ALLBACK *callbac
4320: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4330: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
4340: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
4350: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4380: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4390: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
43a0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
43b0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
43c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
43d0: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
43e0: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
43f0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4400: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4410: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4420: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4430: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
4440: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4450: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
4460: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
4470: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4480: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4490: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
44a0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
44b0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
44c0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
44d0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
44e0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
44f0: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4500: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4510: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4520: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
4530: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
4540: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
4550: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
4560: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
4570: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4580: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4590: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
45a0: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
45b0: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
45c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
45d0: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
45e0: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
45f0: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4600: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4610: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4620: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
4630: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
4640: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4650: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
4660: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
4670: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
4680: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4690: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
46a0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
46b0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
46c0: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
46d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46e0: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
46f0: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4700: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4710: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4720: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
4730: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
4740: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
4750: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4760: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
4770: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
4780: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4790: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
47a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
47b0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
47c0: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
47d0: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
47e0: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
47f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4800: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4810: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4820: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4830: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4840: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4850: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
4860: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
4870: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
4880: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4890: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
48a0: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
48b0: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
48c0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
48d0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
48e0: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
48f0: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4900: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4910: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4920: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
4930: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
4940: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
4950: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
4960: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
4970: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
4980: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4990: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
49a0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
49b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
49c0: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
49d0: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d  * Database is em
49e0: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pty */.#define S
49f0: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a00: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a10: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a20: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4a30: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4a40: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4a50: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4a60: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a80: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4a90: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4aa0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4ab0: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4ac0: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4ad0: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4ae0: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4af0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b00: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b10: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b20: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4b30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b40: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4b50: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4b60: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4b70: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4b80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4b90: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4ba0: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4bb0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4bc0: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4bd0: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69      24   /* Auxi
4be0: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66  liary database f
4bf0: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23  ormat error */.#
4c00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4c10: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4c20: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4c30: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4c40: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4c50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4c60: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
4c70: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
4c80: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
4c90: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
4ca0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4cb0: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4cc0: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4cd0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4ce0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4cf0: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4d00: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4d10: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4d20: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4d30: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4d40: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4d50: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4d60: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4d70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4d80: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4d90: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4da0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4db0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4dc0: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4dd0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4de0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4df0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4e00: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4e10: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4e20: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4e30: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4e40: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4e50: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4e60: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4e70: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a   of 30 integer.*
4e80: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
4e90: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4ea0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4eb0: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4ec0: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4ed0: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4ee0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4ef0: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4f00: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4f10: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4f20: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4f30: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4f40: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4f50: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4f60: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4f70: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4f80: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
4f90: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
4fa0: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
4fb0: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
4fc0: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
4fd0: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
4fe0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
4ff0: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
5000: 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65  ese [extended re
5010: 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20  sult codes] are 
5020: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
5030: 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20  led.** on a per 
5040: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
5050: 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20  ion basis using 
5060: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
5070: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
5080: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f  codes()] API.  O
5090: 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20  r, the extended 
50a0: 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  code for.** the 
50b0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f  most recent erro
50c0: 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  r can be obtaine
50d0: 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
50e0: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
50f0: 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  code()]..*/.#def
5100: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5110: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
5120: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5130: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5140: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5150: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
5160: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5170: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5180: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
5190: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
51a0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51b0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
51c0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
51d0: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
51e0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
51f0: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5200: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
5210: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
5220: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5230: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
5240: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
5250: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
5260: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
5270: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5280: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
5290: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
52a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
52b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
52c0: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
52d0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
52e0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
52f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5300: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
5310: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5320: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
5330: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5340: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
5350: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5360: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
5370: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5380: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
5390: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
53a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
53b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
53c0: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
53d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
53e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
53f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5400: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
5410: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5420: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
5430: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5440: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
5450: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
5460: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
5470: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5480: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20  E_IOERR_LOCK    
5490: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
54a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38  E_IOERR | (15<<8
54b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
54c0: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20  E_IOERR_CLOSE   
54d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
54e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38  E_IOERR | (16<<8
54f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5500: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53  E_IOERR_DIR_CLOS
5510: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
5520: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38  E_IOERR | (17<<8
5530: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5540: 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20  E_IOERR_SHMOPEN 
5550: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5560: 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38  E_IOERR | (18<<8
5570: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5580: 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20  E_IOERR_SHMSIZE 
5590: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
55a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38  E_IOERR | (19<<8
55b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
55c0: 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20  E_IOERR_SHMLOCK 
55d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
55e0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38  E_IOERR | (20<<8
55f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5600: 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20  E_IOERR_SHMMAP  
5610: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5620: 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38  E_IOERR | (21<<8
5630: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5640: 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20  E_IOERR_SEEK    
5650: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5660: 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38  E_IOERR | (22<<8
5670: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5680: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e  E_IOERR_DELETE_N
5690: 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54  OENT      (SQLIT
56a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38  E_IOERR | (23<<8
56b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
56c0: 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20  E_IOERR_MMAP    
56d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
56e0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38  E_IOERR | (24<<8
56f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5700: 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50  E_IOERR_GETTEMPP
5710: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5720: 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38  E_IOERR | (25<<8
5730: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5740: 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48  E_IOERR_CONVPATH
5750: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5760: 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38  E_IOERR | (26<<8
5770: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5780: 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20  E_IOERR_VNODE   
5790: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
57a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38  E_IOERR | (27<<8
57b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
57c0: 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20  E_IOERR_AUTH    
57d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
57e0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38  E_IOERR | (28<<8
57f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5800: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43  E_LOCKED_SHAREDC
5810: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54  ACHE      (SQLIT
5820: 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c  E_LOCKED |  (1<<
5830: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5840: 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59  TE_BUSY_RECOVERY
5850: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5860: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c  TE_BUSY   |  (1<
5870: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5880: 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f  ITE_BUSY_SNAPSHO
5890: 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  T           (SQL
58a0: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32  ITE_BUSY   |  (2
58b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
58c0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
58d0: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
58e0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
58f0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5900: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
5910: 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28  ISDIR          (
5920: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5930: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5940: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5950: 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20  N_FULLPATH      
5960: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5970: 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  N | (3<<8)).#def
5980: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5990: 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20  PEN_CONVPATH    
59a0: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
59b0: 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  PEN | (4<<8)).#d
59c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
59d0: 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20  RUPT_VTAB       
59e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52       (SQLITE_COR
59f0: 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  RUPT | (1<<8)).#
5a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
5a10: 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20  ADONLY_RECOVERY 
5a20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5a30: 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29  ADONLY | (1<<8))
5a40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a50: 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43  READONLY_CANTLOC
5a60: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
5a70: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38  READONLY | (2<<8
5a80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a90: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42  E_READONLY_ROLLB
5aa0: 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  ACK       (SQLIT
5ab0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c  E_READONLY | (3<
5ac0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5ad0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d  ITE_READONLY_DBM
5ae0: 4f 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c  OVED        (SQL
5af0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5b00: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5b10: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5b20: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5b30: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5b40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5b60: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5b70: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5b80: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5b90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5ba0: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5bb0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5bc0: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5bd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5be0: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
5bf0: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
5c00: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
5c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5c20: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
5c30: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5c40: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5c50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c60: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5c70: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
5c80: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5c90: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5ca0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5cb0: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
5cc0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5cd0: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
5ce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5cf0: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
5d00: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5d10: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
5d20: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5d30: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
5d40: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
5d50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
5d60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5d70: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5d80: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
5d90: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5da0: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
5db0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5dc0: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
5dd0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5de0: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
5df0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5e00: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
5e10: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
5e20: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
5e30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5e40: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
5e50: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
5e60: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
5e70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
5e80: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
5e90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
5ea0: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
5eb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
5ec0: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
5ed0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
5ee0: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  TH | (1<<8)).#de
5ef0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c  fine SQLITE_OK_L
5f00: 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20  OAD_PERMANENTLY 
5f10: 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c      (SQLITE_OK |
5f20: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (1<<8))../*.** 
5f30: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
5f40: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
5f50: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
5f60: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
5f70: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
5f80: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
5f90: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
5fa0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
5fb0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
5fc0: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
5fd0: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
5fe0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
5ff0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e  s.xOpen] method.
6000: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6010: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
6020: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6030: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
6040: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6050: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6060: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
6070: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6080: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
6090: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
60a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
60b0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
60c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
60d0: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
60e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
60f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6100: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
6110: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
6120: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
6130: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6140: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
6150: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6160: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
6170: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6180: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
6190: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
61a0: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
61b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
61c0: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20  TE_OPEN_URI     
61d0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
61e0: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  040  /* Ok for s
61f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6200: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6210: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20  TE_OPEN_MEMORY  
6220: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6230: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  080  /* Ok for s
6240: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6250: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6260: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
6270: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6280: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
6290: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
62a0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
62b0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
62c0: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
62d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
62e0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
62f0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
6300: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
6310: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6320: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
6330: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
6340: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
6350: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6360: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
6370: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
6380: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6390: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
63a0: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
63b0: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
63c0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
63d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
63e0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
63f0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
6400: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6410: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6420: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
6430: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
6440: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6450: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6470: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
6480: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
6490: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
64a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
64b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64c0: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
64d0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
64e0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
64f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6500: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6510: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
6520: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
6530: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6540: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6550: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6560: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
6570: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
6580: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6590: 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64   */../* Reserved
65a0: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  :               
65b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30            0x00F0
65c0: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  0000 */../*.** C
65d0: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
65e0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
65f0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
6600: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
6610: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
6620: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6630: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
6640: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
6650: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
6660: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62  or of these.** b
6670: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
6680: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
6690: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
66a0: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
66b0: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
66c0: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
66d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
66e0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
66f0: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
6700: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6710: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
6720: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
6730: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
6740: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
6750: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6760: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
6770: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
6780: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
6790: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
67a0: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
67b0: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
67c0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
67d0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
67e0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
67f0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
6800: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6810: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
6820: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
6830: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
6840: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
6850: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
6860: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
6870: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
6880: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
6890: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
68a0: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
68b0: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
68c0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
68d0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
68e0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
68f0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
6900: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
6910: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
6920: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
6930: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
6940: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6950: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
6960: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6970: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
6980: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
6990: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
69a0: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
69b0: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
69c0: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
69d0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
69e0: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
69f0: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
6a00: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
6a10: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
6a20: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
6a30: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
6a40: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
6a50: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53  nchanged.  The S
6a60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6a70: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6a80: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61  N.** flag indica
6a90: 74 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 63  te that a file c
6aa0: 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64  annot be deleted
6ab0: 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65   when open.  The
6ac0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  .** SQLITE_IOCAP
6ad0: 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20  _IMMUTABLE flag 
6ae0: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
6af0: 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a  he file is on.**
6b00: 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
6b10: 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63   and cannot be c
6b20: 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70  hanged even by p
6b30: 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a  rocesses with.**
6b40: 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c   elevated privil
6b50: 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  eges..*/.#define
6b60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6b70: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20  OMIC            
6b80: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
6b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6ba0: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20  OCAP_ATOMIC512  
6bb0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6bc0: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
6bd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6be0: 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC1K            
6bf0: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64     0x00000004.#d
6c00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6c10: 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20  AP_ATOMIC2K     
6c20: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6c30: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
6c40: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6c50: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6c60: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
6c70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6c80: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20  _ATOMIC8K       
6c90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6ca0: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
6cb0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
6cc0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6cd0: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e  x00000040.#defin
6ce0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6cf0: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20  TOMIC32K        
6d00: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
6d10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6d20: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20  IOCAP_ATOMIC64K 
6d30: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6d40: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
6d50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6d60: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20  E_APPEND        
6d70: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
6d80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6d90: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20  CAP_SEQUENTIAL  
6da0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6db0: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
6dc0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
6dd0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6de0: 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65    0x00000800.#de
6df0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6e00: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6e10: 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31  WRITE    0x00001
6e20: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
6e30: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
6e40: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  LE              
6e50: 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a  0x00002000../*.*
6e60: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
6e70: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
6e80: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
6e90: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
6ea0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6eb0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
6ec0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
6ed0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
6ee0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
6ef0: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
6f00: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
6f10: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6f20: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
6f30: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
6f40: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
6f50: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6f60: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
6f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6f80: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
6f90: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
6fa0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
6fb0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
6fc0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
6fd0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
6fe0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
6ff0: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
7000: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
7010: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
7020: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
7030: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
7040: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7050: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
7060: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
7070: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
7080: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
7090: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
70a0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
70b0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
70c0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
70d0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
70e0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
70f0: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
7100: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
7110: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
7120: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
7130: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
7140: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
7150: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
7160: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
7170: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
7180: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
7190: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
71a0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
71b0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
71c0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
71d0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
71e0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
71f0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
7200: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
7210: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
7220: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a   of fsync()..**.
7230: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73  ** Do not confus
7240: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  e the SQLITE_SYN
7250: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
7260: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
7270: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ags.** with the 
7280: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
7290: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20  ous]=NORMAL and 
72a0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
72b0: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74  ous]=FULL.** set
72c0: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e  tings.  The [syn
72d0: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d  chronous pragma]
72e0: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e   determines when
72f0: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
7300: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f   xSync VFS metho
7310: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c  d occur and appl
7320: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63  ies uniformly ac
7330: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72  ross all platfor
7340: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ms..** The SQLIT
7350: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7360: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7370: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69  LL flags determi
7380: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65  ne how.** energe
7390: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20  tic or rigorous 
73a0: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20  or forceful the 
73b0: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20  sync operations 
73c0: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20  are and.** only 
73d0: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63  make a differenc
73e0: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72  e on Mac OSX for
73f0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c   the default SQL
7400: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68  ite code..** (Th
7410: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d  ird-party VFS im
7420: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69  plementations mi
7430: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68  ght also make th
7440: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  e distinction.**
7450: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
7460: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7470: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7480: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a  , but among the.
7490: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ** operating sys
74a0: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75  tems natively su
74b0: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
74c0: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a  e, only Mac OSX.
74d0: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74  ** cares about t
74e0: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a  he difference.).
74f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7500: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
7510: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
7520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7530: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
7540: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
7550: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7560: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
7570: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7580: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
7590: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a  pen File Handle.
75a0: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  **.** An [sqlite
75b0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72  3_file] object r
75c0: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
75d0: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a  n file in the .*
75e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  * [sqlite3_vfs |
75f0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
7600: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61  yer].  Individua
7610: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a  l OS interface.*
7620: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
7630: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
7640: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
7650: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
7660: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
7670: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
7680: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
7690: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
76a0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
76b0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
76c0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
76d0: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
76e0: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
76f0: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
7700: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
7710: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
7720: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7730: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
7740: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
7750: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
7760: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
7770: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
7780: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
7790: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
77a0: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
77b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
77c0: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
77d0: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
77e0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65  Object.**.** Eve
77f0: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62  ry file opened b
7800: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
7810: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
7820: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a   populates an.**
7830: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7840: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65  object (or, more
7850: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62   commonly, a sub
7860: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
7870: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7880: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f  bject) with a po
7890: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
78a0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
78b0: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ect..** This obj
78c0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
78d0: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
78e0: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
78f0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67  operations.** ag
7900: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
7910: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  ile represented 
7920: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
7930: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  file] object..**
7940: 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69  .** If the [sqli
7950: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7960: 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73  ethod sets the s
7970: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
7980: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a  hods element .**
7990: 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   to a non-NULL p
79a0: 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ointer, then the
79b0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
79c0: 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f  ods.xClose metho
79d0: 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f  d.** may be invo
79e0: 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20  ked even if the 
79f0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7a00: 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61  en] reported tha
7a10: 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68  t it failed.  Th
7a20: 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f  e.** only way to
7a30: 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20   prevent a call 
7a40: 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77  to xClose follow
7a50: 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71  ing a failed [sq
7a60: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7a70: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b  .** is for the [
7a80: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7a90: 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71  n] to set the sq
7aa0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
7ab0: 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74  ods element.** t
7ac0: 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o NULL..**.** Th
7ad0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
7ae0: 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65   to xSync may be
7af0: 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
7b00: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a  SYNC_NORMAL] or.
7b10: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ** [SQLITE_SYNC_
7b20: 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73  FULL].  The firs
7b30: 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20  t choice is the 
7b40: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a  normal fsync()..
7b50: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68  ** The second ch
7b60: 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53  oice is a Mac OS
7b70: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
7b80: 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  c.  The [SQLITE_
7b90: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a  SYNC_DATAONLY].*
7ba0: 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52  * flag may be OR
7bb0: 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74  ed in to indicat
7bc0: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20  e that only the 
7bd0: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65  data of the file
7be0: 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20  .** and not its 
7bf0: 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62  inode needs to b
7c00: 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20  e synced..**.** 
7c10: 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  The integer valu
7c20: 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e  es to xLock() an
7c30: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20  d xUnlock() are 
7c40: 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a  one of.** <ul>.*
7c50: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7c60: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c  OCK_NONE],.** <l
7c70: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7c80: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SHARED],.** <li>
7c90: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
7ca0: 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SERVED],.** <li>
7cb0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
7cc0: 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  NDING], or.** <l
7cd0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7ce0: 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c  EXCLUSIVE]..** <
7cf0: 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20  /ul>.** xLock() 
7d00: 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  increases the lo
7d10: 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65  ck. xUnlock() de
7d20: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
7d30: 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52  ..** The xCheckR
7d40: 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65  eservedLock() me
7d50: 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74  thod checks whet
7d60: 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65  her any database
7d70: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20   connection,.** 
7d80: 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70  either in this p
7d90: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d  rocess or in som
7da0: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c  e other process,
7db0: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45   is holding a RE
7dc0: 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49  SERVED,.** PENDI
7dd0: 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45  NG, or EXCLUSIVE
7de0: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c   lock on the fil
7df0: 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74  e.  It returns t
7e00: 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61  rue.** if such a
7e10: 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64   lock exists and
7e20: 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65   false otherwise
7e30: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c  ..**.** The xFil
7e40: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f  eControl() metho
7e50: 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69  d is a generic i
7e60: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c  nterface that al
7e70: 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56  lows custom.** V
7e80: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7e90: 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63  ns to directly c
7ea0: 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66  ontrol an open f
7eb0: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ile using the.**
7ec0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7ed0: 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66  ontrol()] interf
7ee0: 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ace.  The second
7ef0: 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69   "op" argument i
7f00: 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  s an.** integer 
7f10: 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69  opcode.  The thi
7f20: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  rd argument is a
7f30: 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72   generic pointer
7f40: 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20   intended to.** 
7f50: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63  point to a struc
7f60: 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f  ture that may co
7f70: 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20  ntain arguments 
7f80: 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63  or space in whic
7f90: 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65  h to.** write re
7fa0: 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f  turn values.  Po
7fb0: 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72  tential uses for
7fc0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7fd0: 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63  might be.** func
7fe0: 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20  tions to enable 
7ff0: 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77  blocking locks w
8000: 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f  ith timeouts, to
8010: 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c   change the.** l
8020: 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20  ocking strategy 
8030: 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20  (for example to 
8040: 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63  use dot-file loc
8050: 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a  ks), to inquire.
8060: 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61  ** about the sta
8070: 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f  tus of a lock, o
8080: 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65  r to break stale
8090: 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c   locks.  The SQL
80a0: 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65  ite.** core rese
80b0: 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73  rves all opcodes
80c0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66   less than 100 f
80d0: 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a  or its own use..
80e0: 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72  ** A [file contr
80f0: 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73  ol opcodes | lis
8100: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
8110: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
8120: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
8130: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
8140: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
8150: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
8160: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
8170: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
8180: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
8190: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
81a0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
81b0: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
81c0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
81d0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
81e0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
81f0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
8200: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
8210: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
8220: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
8230: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
8240: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
8250: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
8260: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
8270: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
8280: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
8290: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
82a0: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
82b0: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
82c0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
82d0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
82e0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
82f0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
8300: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
8310: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
8320: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
8330: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
8340: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
8350: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
8360: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8370: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
8380: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8390: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
83a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
83b0: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
83c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
83d0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
83e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
83f0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
8400: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8410: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
8420: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8430: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
8440: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8450: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
8460: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8470: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
8480: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8490: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
84a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
84b0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
84c0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
84d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
84e0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
84f0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
8500: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
8510: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
8520: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8530: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
8540: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
8550: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
8560: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
8570: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
8580: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
8590: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
85a0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
85b0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
85c0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
85d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
85e0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
85f0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
8600: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
8610: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
8620: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
8630: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
8640: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
8650: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
8660: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
8670: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
8680: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
8690: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
86a0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
86b0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
86c0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
86d0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
86e0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
86f0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
8700: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
8710: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
8720: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
8730: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
8740: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
8750: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
8760: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
8770: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
8780: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
8790: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
87a0: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
87b0: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
87c0: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
87d0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
87e0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
87f0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
8800: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
8810: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
8820: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
8830: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8840: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8850: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
8860: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
8870: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
8880: 20 20 69 6e 74 20 28 53 51 4c 49 54 45 5f 43 41    int (SQLITE_CA
8890: 4c 4c 42 41 43 4b 20 2a 78 43 6c 6f 73 65 29 28  LLBACK *xClose)(
88a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
88b0: 20 20 69 6e 74 20 28 53 51 4c 49 54 45 5f 43 41    int (SQLITE_CA
88c0: 4c 4c 42 41 43 4b 20 2a 78 52 65 61 64 29 28 73  LLBACK *xRead)(s
88d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
88e0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
88f0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8900: 73 74 29 3b 0a 20 20 69 6e 74 20 28 53 51 4c 49  st);.  int (SQLI
8910: 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 57 72  TE_CALLBACK *xWr
8920: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
8930: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
8940: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8950: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8960: 0a 20 20 69 6e 74 20 28 53 51 4c 49 54 45 5f 43  .  int (SQLITE_C
8970: 41 4c 4c 42 41 43 4b 20 2a 78 54 72 75 6e 63 61  ALLBACK *xTrunca
8980: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8990: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
89a0: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 53   size);.  int (S
89b0: 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a  QLITE_CALLBACK *
89c0: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
89d0: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
89e0: 3b 0a 20 20 69 6e 74 20 28 53 51 4c 49 54 45 5f  ;.  int (SQLITE_
89f0: 43 41 4c 4c 42 41 43 4b 20 2a 78 46 69 6c 65 53  CALLBACK *xFileS
8a00: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
8a10: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8a20: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
8a30: 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43   (SQLITE_CALLBAC
8a40: 4b 20 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65  K *xLock)(sqlite
8a50: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
8a60: 20 69 6e 74 20 28 53 51 4c 49 54 45 5f 43 41 4c   int (SQLITE_CAL
8a70: 4c 42 41 43 4b 20 2a 78 55 6e 6c 6f 63 6b 29 28  LBACK *xUnlock)(
8a80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8a90: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 53 51 4c 49  nt);.  int (SQLI
8aa0: 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 43 68  TE_CALLBACK *xCh
8ab0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
8ac0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8ad0: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
8ae0: 20 69 6e 74 20 28 53 51 4c 49 54 45 5f 43 41 4c   int (SQLITE_CAL
8af0: 4c 42 41 43 4b 20 2a 78 46 69 6c 65 43 6f 6e 74  LBACK *xFileCont
8b00: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
8b10: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
8b20: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
8b30: 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20  SQLITE_CALLBACK 
8b40: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
8b50: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8b60: 69 6e 74 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c  int (SQLITE_CALL
8b70: 42 41 43 4b 20 2a 78 44 65 76 69 63 65 43 68 61  BACK *xDeviceCha
8b80: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
8b90: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8ba0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8bb0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8bc0: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
8bd0: 74 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  t (SQLITE_CALLBA
8be0: 43 4b 20 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  CK *xShmMap)(sql
8bf0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8c00: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
8c10: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
8c20: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 53 51 4c  e**);.  int (SQL
8c30: 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 53  ITE_CALLBACK *xS
8c40: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
8c50: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
8c60: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
8c70: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 53 51  ags);.  void (SQ
8c80: 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78  LITE_CALLBACK *x
8c90: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
8ca0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
8cb0: 74 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  t (SQLITE_CALLBA
8cc0: 43 4b 20 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  CK *xShmUnmap)(s
8cd0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8ce0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
8cf0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8d00: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8d10: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69  version 2 */.  i
8d20: 6e 74 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42  nt (SQLITE_CALLB
8d30: 41 43 4b 20 2a 78 46 65 74 63 68 29 28 73 71 6c  ACK *xFetch)(sql
8d40: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8d50: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8d60: 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20   int iAmt, void 
8d70: 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 53 51  **pp);.  int (SQ
8d80: 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78  LITE_CALLBACK *x
8d90: 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33  Unfetch)(sqlite3
8da0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8db0: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69  int64 iOfst, voi
8dc0: 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  d *p);.  /* Meth
8dd0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8de0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8df0: 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69  3 */.  /* Additi
8e00: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79  onal methods may
8e10: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
8e20: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a  ure releases */.
8e30: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
8e40: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c  EF: Standard Fil
8e50: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65  e Control Opcode
8e60: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
8e70: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
8e80: 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74  odes} {file cont
8e90: 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a  rol opcode}.**.*
8ea0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
8eb0: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70  constants are op
8ec0: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46  codes for the xF
8ed0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
8ee0: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  d.** of the [sql
8ef0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
8f00: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20   object and for 
8f10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
8f20: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20  e_control()].** 
8f30: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
8f40: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53   <ul>.** <li>[[S
8f50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
8f60: 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  STATE]].** The [
8f70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
8f80: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
8f90: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
8fa0: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
8fb0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
8fc0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8fd0: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
8fe0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
8ff0: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
9000: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
9010: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
9020: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
9030: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
9040: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
9050: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
9060: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
9070: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
9080: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
9090: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
90a0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
90b0: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
90c0: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
90d0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
90e0: 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  d is only availa
90f0: 62 6c 65 20 77 68 65 6e 20 74 68 65 20 53 51 4c  ble when the SQL
9100: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70  ITE_TEST.** comp
9110: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
9120: 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
9130: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9140: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a  L_SIZE_HINT]].**
9150: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9160: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70  TL_SIZE_HINT] op
9170: 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20  code is used by 
9180: 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74  SQLite to give t
9190: 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20  he VFS.** layer 
91a0: 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61  a hint of how la
91b0: 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  rge the database
91c0: 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20   file will grow 
91d0: 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65  to be during the
91e0: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e  .** current tran
91f0: 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68  saction.  This h
9200: 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61  int is not guara
9210: 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75  nteed to be accu
9220: 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69  rate but it.** i
9230: 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20  s often close.  
9240: 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56  The underlying V
9250: 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20  FS might choose 
9260: 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64  to preallocate d
9270: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
9280: 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74  space based on t
9290: 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65  his hint in orde
92a0: 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73  r to help writes
92b0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
92c0: 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73  .** file run fas
92d0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ter..**.** <li>[
92e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
92f0: 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  UNK_SIZE]].** Th
9300: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9310: 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f  CHUNK_SIZE] opco
9320: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  de is used to re
9330: 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56  quest that the V
9340: 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e  FS.** extends an
9350: 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20  d truncates the 
9360: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e  database file in
9370: 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a   chunks of a siz
9380: 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
9390: 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20  y the user. The 
93a0: 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
93b0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  to [sqlite3_file
93c0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75  _control()] shou
93d0: 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20  ld .** point to 
93e0: 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65  an integer (type
93f0: 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67   int) containing
9400: 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73   the new chunk-s
9410: 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f  ize to use.** fo
9420: 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20  r the nominated 
9430: 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61  database. Alloca
9440: 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69  ting database fi
9450: 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67  le space in larg
9460: 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79  e.** chunks (say
9470: 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c   1MB at a time),
9480: 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65   may reduce file
9490: 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74  -system fragment
94a0: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70  ation and.** imp
94b0: 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
94c0: 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73   on some systems
94d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
94e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
94f0: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65  POINTER]].** The
9500: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46   [SQLITE_FCNTL_F
9510: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  ILE_POINTER] opc
9520: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f  ode is used to o
9530: 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a  btain a pointer.
9540: 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
9550: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
9560: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
9570: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
9580: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
9590: 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b  ion.  See also [
95a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55  SQLITE_FCNTL_JOU
95b0: 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a  RNAL_POINTER]..*
95c0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
95d0: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
95e0: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65  POINTER]].** The
95f0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a   [SQLITE_FCNTL_J
9600: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20  OURNAL_POINTER] 
9610: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9620: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
9630: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9640: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9650: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9660: 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66  th the journal f
9670: 69 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74  ile (either.** t
9680: 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75  he [rollback jou
9690: 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72  rnal] or the [wr
96a0: 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20  ite-ahead log]) 
96b0: 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
96c0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
96d0: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c  nection.  See al
96e0: 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  so [SQLITE_FCNTL
96f0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a  _FILE_POINTER]..
9700: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9710: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
9720: 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f  ITTED]].** No lo
9730: 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a  nger in use..**.
9740: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9750: 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20  FCNTL_SYNC]].** 
9760: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9770: 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69  L_SYNC] opcode i
9780: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
9790: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
97a0: 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20   and.** sent to 
97b0: 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74  the VFS immediat
97c0: 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78  ely before the x
97d0: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69  Sync method is i
97e0: 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64  nvoked on a.** d
97f0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73  atabase file des
9800: 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20  criptor. Or, if 
9810: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9820: 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
9830: 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20  .** because the 
9840: 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75  user has configu
9850: 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20  red SQLite with 
9860: 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  .** [PRAGMA sync
9870: 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41  hronous | PRAGMA
9880: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46   synchronous=OFF
9890: 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  ] it is invoked 
98a0: 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20  in place .** of 
98b0: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
98c0: 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c  . In most cases,
98d0: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   the pointer arg
98e0: 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74  ument passed wit
98f0: 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63  h.** this file-c
9900: 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20  ontrol is NULL. 
9910: 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20  However, if the 
9920: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
9930: 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a   being synced.**
9940: 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75   as part of a mu
9950: 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d  lti-database com
9960: 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e  mit, the argumen
9970: 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75  t points to a nu
9980: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
9990: 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
99a0: 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  g the transactio
99b0: 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61  ns master-journa
99c0: 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53  l file name. VFS
99d0: 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e  es that .** do n
99e0: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
99f0: 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  nal should silen
9a00: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
9a10: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
9a20: 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20  ions .** should 
9a30: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  not call [sqlite
9a40: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9a50: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9a60: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9a70: 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74  ay .** disrupt t
9a80: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  he operation of 
9a90: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9aa0: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
9ab0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9ac0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9ad0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
9ae0: 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  ETWO]].** The [S
9af0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
9b00: 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63  IT_PHASETWO] opc
9b10: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
9b20: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53   internally by S
9b30: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e  QLite.** and sen
9b40: 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74  t to the VFS aft
9b50: 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
9b60: 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74   has been commit
9b70: 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a  ted immediately.
9b80: 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68  ** but before th
9b90: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e  e database is un
9ba0: 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68  locked. VFSes th
9bb0: 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  at do not need t
9bc0: 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68  his signal.** sh
9bd0: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
9be0: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
9bf0: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  . Applications s
9c00: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a  hould not call.*
9c10: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
9c20: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
9c30: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
9c40: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72  oing so may disr
9c50: 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72  upt the .** oper
9c60: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
9c70: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
9c80: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
9c90: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
9ca0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
9cb0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a  N32_AV_RETRY]].*
9cc0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9cd0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9ce0: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TRY] opcode is u
9cf0: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
9d00: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65   automatic.** re
9d10: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69  try counts and i
9d20: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72  ntervals for cer
9d30: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70  tain disk I/O op
9d40: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  erations for the
9d50: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53  .** windows [VFS
9d60: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  ] in order to pr
9d70: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
9d80: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65   in the presence
9d90: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75   of.** anti-viru
9da0: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20  s programs.  By 
9db0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e  default, the win
9dc0: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65  dows VFS will re
9dd0: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a  try file read,.*
9de0: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e  * file write, an
9df0: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70  d file delete op
9e00: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31  erations up to 1
9e10: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20  0 times, with a 
9e20: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d  delay.** of 25 m
9e30: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f  illiseconds befo
9e40: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74  re the first ret
9e50: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20  ry and with the 
9e60: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67  delay increasing
9e70: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69  .** by an additi
9e80: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63  onal 25 millisec
9e90: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73  onds with each s
9ea0: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e  ubsequent retry.
9eb0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
9ec0: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77   allows these tw
9ed0: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74  o values (10 ret
9ee0: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c  ries and 25 mill
9ef0: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61  iseconds of dela
9f00: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75  y).** to be adju
9f10: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65  sted.  The value
9f20: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f  s are changed fo
9f30: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  r all database c
9f40: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69  onnections.** wi
9f50: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  thin the same pr
9f60: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75  ocess.  The argu
9f70: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
9f80: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66  r to an array of
9f90: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73   two.** integers
9fa0: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
9fb0: 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e   integer i the n
9fc0: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
9fd0: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
9fe0: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
9ff0: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
a000: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
a010: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
a020: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
a030: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
a040: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
a050: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
a060: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
a070: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
a080: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
a090: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
a0a0: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
a0b0: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
a0c0: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
a0d0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
a0e0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
a0f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a100: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
a110: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a120: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
a130: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
a140: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
a150: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
a160: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
a170: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
a180: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
a190: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
a1a0: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
a1b0: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  g and shared mem
a1c0: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66  ory files used f
a1d0: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
a1e0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
a1f0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
a200: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
a210: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
a220: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
a230: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
a240: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
a250: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
a260: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
a270: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
a280: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
a290: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
a2a0: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
a2b0: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
a2c0: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
a2d0: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
a2e0: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
a2f0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
a300: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
a310: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
a320: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
a330: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
a340: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
a350: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
a360: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
a370: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
a380: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
a390: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
a3a0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
a3b0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a3c0: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
a3d0: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
a3e0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
a3f0: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
a400: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
a410: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
a420: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
a430: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
a440: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
a450: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
a460: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
a470: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
a480: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
a490: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
a4a0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
a4b0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a4c0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
a4d0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
a4e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
a4f0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a500: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
a510: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
a520: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
a530: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
a540: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
a550: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
a560: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
a570: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
a580: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
a590: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
a5a0: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
a5b0: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
a5c0: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
a5d0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
a5e0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
a5f0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a600: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
a610: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
a620: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
a630: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
a640: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
a650: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
a660: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
a670: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
a680: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
a690: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
a6a0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
a6b0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
a6c0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
a6d0: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a6e0: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
a6f0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a700: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
a710: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a720: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
a730: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
a740: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
a750: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
a760: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
a770: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
a780: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
a790: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
a7a0: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
a7b0: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
a7c0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
a7d0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
a7e0: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
a7f0: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
a800: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
a810: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
a820: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a830: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
a840: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a850: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
a860: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
a870: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
a880: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
a890: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
a8a0: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
a8b0: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
a8c0: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
a8d0: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
a8e0: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
a8f0: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
a900: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
a910: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
a920: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
a930: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
a940: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
a950: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
a960: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
a970: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
a980: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a990: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
a9a0: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
a9b0: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
a9c0: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
a9d0: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
a9e0: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
a9f0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
aa00: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
aa10: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
aa20: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
aa30: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
aa40: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
aa50: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
aa60: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
aa70: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
aa80: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
aa90: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
aaa0: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
aab0: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
aac0: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
aad0: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
aae0: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
aaf0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
ab00: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
ab10: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
ab20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
ab30: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66  OINTER] opcode f
ab40: 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74  inds a pointer t
ab50: 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a  o the top-level.
ab60: 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65  ** [VFSes] curre
ab70: 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28  ntly in use.  ^(
ab80: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69  The argument X i
ab90: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c  n.** sqlite3_fil
aba0: 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c  e_control(db,SQL
abb0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
abc0: 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65  INTER,X) must be
abd0: 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71  .** of type "[sq
abe0: 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20  lite3_vfs] **". 
abf0: 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69   This opcodes wi
ac00: 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20  ll set *X.** to 
ac10: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
ac20: 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29   top-level VFS.)
ac30: 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65  ^.** ^When there
ac40: 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46   are multiple VF
ac50: 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73  S shims in the s
ac60: 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64  tack, this opcod
ac70: 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75  e finds the.** u
ac80: 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f  pper-most shim o
ac90: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
aca0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
acb0: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
acc0: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
acd0: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
ace0: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
acf0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
ad00: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
ad10: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
ad20: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
ad30: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
ad40: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
ad50: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
ad60: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
ad70: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
ad80: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
ad90: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
ada0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
adb0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
adc0: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
add0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
ade0: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
adf0: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
ae00: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
ae10: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
ae20: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
ae30: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
ae40: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
ae50: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
ae60: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
ae70: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
ae80: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
ae90: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
aea0: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
aeb0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
aec0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
aed0: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
aee0: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
aef0: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
af00: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
af10: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
af20: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
af30: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
af40: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
af50: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
af60: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
af70: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
af80: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
af90: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
afa0: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
afb0: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
afc0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
afd0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
afe0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
aff0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
b000: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
b010: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
b020: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
b030: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
b040: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
b050: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
b060: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
b070: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
b080: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
b090: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
b0a0: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
b0b0: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
b0c0: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
b0d0: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
b0e0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
b0f0: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e   if result strin
b100: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68  g is NULL, or th
b110: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  at returns a cop
b120: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  y.** of the resu
b130: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65  lt string if the
b140: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e   string is non-N
b150: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ULL..** ^If the 
b160: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b170: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
b180: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
b190: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
b1a0: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
b1b0: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
b1c0: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
b1d0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
b1e0: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
b1f0: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
b200: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
b210: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
b220: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
b230: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
b240: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
b250: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
b260: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
b270: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
b280: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
b290: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
b2a0: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
b2b0: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
b2c0: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
b2d0: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
b2e0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
b2f0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b300: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b310: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
b320: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
b330: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
b340: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
b350: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
b360: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
b370: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
b380: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
b390: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
b3a0: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
b3b0: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
b3c0: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
b3d0: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
b3e0: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
b3f0: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
b400: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
b410: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
b420: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
b430: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
b440: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
b450: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
b460: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
b470: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
b480: 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43   (SQLITE_CALLBAC
b490: 4b 20 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49  K *)(void *)). I
b4a0: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
b4b0: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
b4c0: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
b4d0: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
b4e0: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
b4f0: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
b500: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
b510: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
b520: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
b530: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
b540: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
b550: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
b560: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
b570: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
b580: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
b590: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
b5a0: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
b5b0: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
b5c0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b5d0: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
b5e0: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
b5f0: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
b600: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
b610: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b620: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
b630: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
b640: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
b650: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
b660: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
b670: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
b680: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
b690: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
b6a0: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
b6b0: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
b6c0: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
b6d0: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
b6e0: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
b6f0: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
b700: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
b710: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
b720: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
b730: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
b740: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b750: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
b760: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
b770: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
b780: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
b790: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
b7a0: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
b7b0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b7c0: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b7d0: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
b7e0: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
b7f0: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
b800: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
b810: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
b820: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
b830: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
b840: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
b850: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
b860: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
b870: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
b880: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
b890: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
b8a0: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
b8b0: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
b8c0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
b8d0: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
b8e0: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
b8f0: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
b900: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
b910: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
b920: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
b930: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
b940: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
b950: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
b960: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
b970: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
b980: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
b990: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
b9a0: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
b9b0: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
b9c0: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
b9d0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
b9e0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
b9f0: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
ba00: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
ba10: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
ba20: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
ba30: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
ba40: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
ba50: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
ba60: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
ba70: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
ba80: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
ba90: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
baa0: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
bab0: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
bac0: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
bad0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
bae0: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
baf0: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
bb00: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
bb10: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
bb20: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
bb30: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
bb40: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
bb50: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
bb60: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
bb70: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
bb80: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
bb90: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
bba0: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
bbb0: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
bbc0: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
bbd0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
bbe0: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
bbf0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
bc00: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
bc10: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
bc20: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
bc30: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
bc40: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
bc50: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
bc60: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
bc70: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
bc80: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
bc90: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
bca0: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
bcb0: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
bcc0: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
bcd0: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
bce0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
bcf0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
bd00: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
bd10: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
bd20: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
bd30: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
bd40: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
bd50: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
bd60: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
bd70: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
bd80: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
bd90: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
bda0: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
bdb0: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
bdc0: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
bdd0: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
bde0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
bdf0: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
be00: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
be10: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
be20: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
be30: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
be40: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
be50: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  OCK]].** The [SQ
be60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
be70: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61  LOCK] is a signa
be80: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79  l to the VFS lay
be90: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  er that it might
bea0: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65  .** be advantage
beb0: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20  ous to block on 
bec0: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63  the next WAL loc
bed0: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73  k if the lock is
bee0: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79   not immediately
bef0: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20  .** available.  
bf00: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65  The WAL subsyste
bf10: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69  m issues this si
bf20: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65  gnal during rare
bf30: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65  .** circumstance
bf40: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  s in order to fi
bf50: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68  x a problem with
bf60: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73   priority invers
bf70: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ion..** Applicat
bf80: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e  ions should <em>
bf90: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69  not</em> use thi
bfa0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a  s file-control..
bfb0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
bfc0: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d  TE_FCNTL_ZIPVFS]
bfd0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
bfe0: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f  _FCNTL_ZIPVFS] o
bff0: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
c000: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f  nted by zipvfs o
c010: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a  nly. All other.*
c020: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  * VFS should ret
c030: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
c040: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63  UND for this opc
c050: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ode..**.** <li>[
c060: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42  [SQLITE_FCNTL_RB
c070: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  U]].** The [SQLI
c080: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70  TE_FCNTL_RBU] op
c090: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
c0a0: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69  ted by the speci
c0b0: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a  al VFS used by.*
c0c0: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73  * the RBU extens
c0d0: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f  ion only.  All o
c0e0: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20  ther VFS should 
c0f0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
c100: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68  TFOUND for.** th
c110: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20  is opcode.  .** 
c120: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
c130: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
c140: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
c150: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
c160: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
c170: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
c180: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
c190: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
c1a0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
c1b0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
c1c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
c1d0: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
c1e0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
c1f0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
c200: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
c210: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
c220: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
c230: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
c240: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
c250: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
c260: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
c270: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
c280: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
c290: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
c2a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c2b0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
c2c0: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
c2d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c2e0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
c2f0: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
c300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c310: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
c320: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
c330: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c340: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
c350: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
c360: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c370: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
c380: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
c390: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c3a0: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
c3b0: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
c3c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c3d0: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
c3e0: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
c3f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
c400: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
c410: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65        16.#define
c420: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d   SQLITE_FCNTL_MM
c430: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  AP_SIZE         
c440: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20       18.#define 
c450: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
c460: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CE              
c470: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53      19.#define S
c480: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
c490: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20  MOVED           
c4a0: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51     20.#define SQ
c4b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20  LITE_FCNTL_SYNC 
c4c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c4d0: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    21.#define SQL
c4e0: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
c4f0: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20  _PHASETWO       
c500: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   22.#define SQLI
c510: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
c520: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
c530: 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  23.#define SQLIT
c540: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
c550: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  K              2
c560: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
c570: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20  _FCNTL_ZIPVFS   
c580: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
c590: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c5a0: 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20  FCNTL_RBU       
c5b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a               26.
c5c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c5d0: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
c5e0: 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a 23              27.#
c5f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c600: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e  NTL_JOURNAL_POIN
c610: 54 45 52 20 20 20 20 20 20 20 20 32 38 0a 0a 2f  TER        28../
c620: 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d  * deprecated nam
c630: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
c640: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_GET_LOCKPRO
c650: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
c660: 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43  TE_FCNTL_GET_LOC
c670: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
c680: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
c690: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
c6a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
c6b0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a  T_LOCKPROXYFILE.
c6c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
c6d0: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
c6e0: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
c6f0: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a  TL_LAST_ERRNO...
c700: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c710: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
c720: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
c730: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
c740: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
c750: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
c760: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
c770: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
c780: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
c790: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
c7a0: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
c7b0: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
c7c0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
c7d0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
c7e0: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
c7f0: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
c800: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
c810: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
c820: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
c830: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
c840: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
c850: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
c860: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
c870: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
c880: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
c890: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
c8a0: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ce Object.**.** 
c8b0: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
c8c0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
c8d0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
c8e0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
c8f0: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
c900: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
c910: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
c920: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
c930: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
c940: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
c950: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
c960: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
c970: 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68  tem".  See.** th
c980: 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63  e [VFS | VFS doc
c990: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
c9a0: 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74  further informat
c9b0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76  ion..**.** The v
c9c0: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72  alue of the iVer
c9d0: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
c9e0: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
c9f0: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a  y be larger in.*
ca00: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * future version
ca10: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64  s of SQLite.  Ad
ca20: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
ca30: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
ca40: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  to this.** objec
ca50: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73  t when the iVers
ca60: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63  ion value is inc
ca70: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68  reased.  Note th
ca80: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
ca90: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
caa0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
cab0: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
cac0: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  nsaction between
cad0: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
cae0: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36  on 3.5.9 and 3.6
caf0: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  .0 and yet the i
cb00: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
cb10: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65  s not.** modifie
cb20: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
cb30: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
cb40: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
cb50: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
cb60: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
cb70: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
cb80: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
cb90: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
cba0: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
cbb0: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
cbc0: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
cbd0: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
cbe0: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
cbf0: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
cc00: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
cc10: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
cc20: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
cc30: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
cc40: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
cc50: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
cc60: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
cc70: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
cc80: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
cc90: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
cca0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
ccb0: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
ccc0: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
ccd0: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
cce0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
ccf0: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
cd00: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
cd10: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
cd20: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
cd30: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
cd40: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
cd50: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
cd60: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
cd70: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
cd80: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
cd90: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
cda0: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
cdb0: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
cdc0: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
cdd0: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
cde0: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
cdf0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
ce00: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
ce10: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
ce20: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
ce30: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
ce40: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
ce50: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
ce60: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
ce70: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
ce80: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
ce90: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
cea0: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
ceb0: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
cec0: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
ced0: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
cee0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a  3_vfs.xOpen]].**
cef0: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
cf00: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69  ees that the zFi
cf10: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
cf20: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20   to xOpen.** is 
cf30: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
cf40: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20  inter or string 
cf50: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
cf60: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
cf70: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61   with an optiona
cf80: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a  l suffix added..
cf90: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20  ** ^If a suffix 
cfa0: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  is added to the 
cfb0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
cfc0: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20  ter, it will.** 
cfd0: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e  consist of a sin
cfe0: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65  gle "-" characte
cff0: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f  r followed by no
d000: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31   more than.** 11
d010: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e   alphanumeric an
d020: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74  d/or "-" charact
d030: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ers..** ^SQLite 
d040: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
d050: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
d060: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
d070: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
d080: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
d090: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42   is.** called. B
d0a0: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
d0b0: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
d0c0: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
d0d0: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
d0e0: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
d0f0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
d100: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
d110: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
d120: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
d130: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
d140: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
d150: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
d160: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
d170: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
d180: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74  * must invent it
d190: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
d1a0: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
d1b0: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68  e.  ^Whenever th
d1c0: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
d1d0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
d1e0: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
d1f0: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
d200: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
d210: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
d220: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
d230: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
d240: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
d250: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
d260: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
d270: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
d280: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
d290: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
d2a0: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
d2b0: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
d2c0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
d2d0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
d2e0: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
d2f0: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
d300: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
d310: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
d320: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
d330: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70  ATE]. .** If xOp
d340: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
d350: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
d360: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
d370: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
d380: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
d390: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
d3a0: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
d3b0: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
d3c0: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77  **.** ^(SQLite w
d3d0: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
d3e0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
d3f0: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
d400: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
d410: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
d420: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
d430: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
d440: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
d450: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
d460: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d470: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
d480: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d490: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
d4a0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
d4b0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
d4c0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
d4d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
d4e0: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
d4f0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d500: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
d510: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d520: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
d530: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
d540: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a  ITE_OPEN_WAL].**
d550: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
d560: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
d570: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
d580: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
d590: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
d5a0: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
d5b0: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
d5c0: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
d5d0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
d5e0: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
d5f0: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
d600: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
d610: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
d620: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
d630: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
d640: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
d650: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
d660: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
d670: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
d680: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
d690: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
d6a0: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
d6b0: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
d6c0: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
d6d0: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
d6e0: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
d6f0: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
d700: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
d710: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
d720: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
d730: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
d740: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
d750: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
d760: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
d770: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
d780: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
d790: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
d7a0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
d7b0: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
d7c0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
d7d0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
d7e0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
d7f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
d800: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
d810: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
d820: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d830: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
d840: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
d850: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
d860: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
d870: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  d.  ^The [SQLITE
d880: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
d890: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
d8a0: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74  set for TEMP dat
d8b0: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72  abases and their
d8c0: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73   journals, trans
d8d0: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65  ient.** database
d8e0: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61  s, and subjourna
d8f0: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ls..**.** ^The [
d900: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
d910: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
d920: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
d930: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
d940: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
d950: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
d960: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
d970: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
d980: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
d990: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
d9a0: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
d9b0: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
d9c0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
d9d0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
d9e0: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
d9f0: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
da00: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
da10: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
da20: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
da30: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
da40: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
da50: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
da60: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
da70: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
da80: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
da90: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
daa0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
dab0: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
dac0: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
dad0: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73  ..**.** ^At leas
dae0: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
daf0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
db00: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
db10: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
db20: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
db30: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
db40: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
db50: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
db60: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e  Open.  The xOpen
db70: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
db80: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
db90: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
dba0: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
dbb0: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20  st fill it in.  
dbc0: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  Note that.** the
dbd0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75   xOpen method mu
dbe0: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  st set the sqlit
dbf0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
dc00: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20   to either.** a 
dc10: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69  valid [sqlite3_i
dc20: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
dc30: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78  t or to NULL.  x
dc40: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20  Open must do.** 
dc50: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65  this even if the
dc60: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51   open fails.  SQ
dc70: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61  Lite expects tha
dc80: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
dc90: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65  le.pMethods.** e
dca0: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76  lement will be v
dcb0: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e  alid after xOpen
dcc0: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c   returns regardl
dcd0: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
dce0: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65  ss.** or failure
dcf0: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61   of the xOpen ca
dd00: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  ll..**.** [[sqli
dd10: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d  te3_vfs.xAccess]
dd20: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20  ].** ^The flags 
dd30: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
dd40: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
dd50: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
dd60: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
dd70: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
dd80: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
dd90: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
dda0: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
ddb0: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
ddc0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
ddd0: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
dde0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
ddf0: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
de00: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
de10: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
de20: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20  ble.   The file 
de30: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65  can be a.** dire
de40: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ctory..**.** ^SQ
de50: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
de60: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
de70: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
de80: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
de90: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
dea0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54  FullPathname.  T
deb0: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
dec0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
ded0: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
dee0: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
def0: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
df00: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74  hods. If the out
df10: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
df20: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
df30: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
df40: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
df50: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
df60: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
df70: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
df80: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
df90: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
dfa0: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
dfb0: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
dfc0: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
dfd0: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
dfe0: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
dff0: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
e000: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
e010: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75  ), xSleep(), xCu
e020: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64  rrentTime(), and
e030: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
e040: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  64().** interfac
e050: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  es are not stric
e060: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
e070: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
e080: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
e090: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
e0a0: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
e0b0: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
e0c0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
e0d0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
e0e0: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
e0f0: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
e100: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
e110: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
e120: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
e130: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
e140: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
e150: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
e160: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
e170: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
e180: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
e190: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
e1a0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
e1b0: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
e1c0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
e1d0: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68  onds given.  ^Th
e1e0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
e1f0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
e200: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
e210: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
e220: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
e230: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f  time as.** a flo
e240: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
e250: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72  e..** ^The xCurr
e260: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
e270: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61  ethod returns, a
e280: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  s an integer, th
e290: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20  e Julian.** Day 
e2a0: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65  Number multiplie
e2b0: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
e2c0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
e2d0: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
e2e0: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
e2f0: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
e300: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
e310: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
e320: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
e330: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
e340: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
e350: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
e360: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
e370: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
e380: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
e390: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
e3a0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
e3b0: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
e3c0: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
e3d0: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
e3e0: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
e3f0: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a  navailable..**.*
e400: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65  * ^The xSetSyste
e410: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73  mCall(), xGetSys
e420: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78  temCall(), and x
e430: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  NestSystemCall()
e440: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
e450: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74  re not used by t
e460: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he SQLite core. 
e470: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20   These optional 
e480: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
e490: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f  rovided.** by so
e4a0: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69  me VFSes to faci
e4b0: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f  litate testing o
e4c0: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20  f the VFS code. 
e4d0: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a  By overriding .*
e4e0: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77  * system calls w
e4f0: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e  ith functions un
e500: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c  der its control,
e510: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20   a test program 
e520: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20  can.** simulate 
e530: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72  faults and error
e540: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74   conditions that
e550: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
e560: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a   be difficult.**
e570: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74   or impossible t
e580: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73  o induce.  The s
e590: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c  et of system cal
e5a0: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  ls that can be o
e5b0: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72  verridden.** var
e5c0: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53  ies from one VFS
e5d0: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64   to another, and
e5e0: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f   from one versio
e5f0: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46  n of the same VF
e600: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74  S to the.** next
e610: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
e620: 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69  that use these i
e630: 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62  nterfaces must b
e640: 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61  e prepared for a
e650: 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20  ny.** or all of 
e660: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
e670: 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66   to be NULL or f
e680: 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f  or their behavio
e690: 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66  r to change.** f
e6a0: 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
e6b0: 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70  to the next.  Ap
e6c0: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
e6d0: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61  not attempt to a
e6e0: 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20  ccess.** any of 
e6f0: 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66  these methods if
e700: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66   the iVersion of
e710: 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73   the VFS is less
e720: 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65   than 3..*/.type
e730: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
e740: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
e750: 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64  fs;.typedef void
e760: 20 28 53 51 4c 49 54 45 5f 53 59 53 41 50 49 20   (SQLITE_SYSAPI 
e770: 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c  *sqlite3_syscall
e780: 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72  _ptr)(void);.str
e790: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
e7a0: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
e7b0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
e7c0: 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f  Structure versio
e7d0: 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e  n number (curren
e7e0: 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20  tly 3) */.  int 
e7f0: 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20  szOsFile;       
e800: 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20       /* Size of 
e810: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
e820: 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74  e3_file */.  int
e830: 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20   mxPathname;    
e840: 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
e850: 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c   file pathname l
e860: 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74  ength */.  sqlit
e870: 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20  e3_vfs *pNext;  
e880: 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69      /* Next regi
e890: 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20  stered VFS */.  
e8a0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e8b0: 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  e;       /* Name
e8c0: 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c   of this virtual
e8d0: 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a   file system */.
e8e0: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
e8f0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f  ;          /* Po
e900: 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  inter to applica
e910: 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61  tion-specific da
e920: 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 53 51 4c  ta */.  int (SQL
e930: 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 4f  ITE_CALLBACK *xO
e940: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
e950: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e960: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
e970: 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
e980: 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
e990: 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
e9a0: 20 20 69 6e 74 20 28 53 51 4c 49 54 45 5f 43 41    int (SQLITE_CA
e9b0: 4c 4c 42 41 43 4b 20 2a 78 44 65 6c 65 74 65 29  LLBACK *xDelete)
e9c0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e9d0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e9e0: 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a  , int syncDir);.
e9f0: 20 20 69 6e 74 20 28 53 51 4c 49 54 45 5f 43 41    int (SQLITE_CA
ea00: 4c 4c 42 41 43 4b 20 2a 78 41 63 63 65 73 73 29  LLBACK *xAccess)
ea10: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
ea20: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
ea30: 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74  , int flags, int
ea40: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
ea50: 74 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  t (SQLITE_CALLBA
ea60: 43 4b 20 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  CK *xFullPathnam
ea70: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
ea80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
ea90: 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68  me, int nOut, ch
eaa0: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69  ar *zOut);.  voi
eab0: 64 20 2a 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42  d *(SQLITE_CALLB
eac0: 41 43 4b 20 2a 78 44 6c 4f 70 65 6e 29 28 73 71  ACK *xDlOpen)(sq
ead0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
eae0: 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
eaf0: 65 29 3b 0a 20 20 76 6f 69 64 20 28 53 51 4c 49  e);.  void (SQLI
eb00: 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 44 6c  TE_CALLBACK *xDl
eb10: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
eb20: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
eb30: 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a  char *zErrMsg);.
eb40: 20 20 76 6f 69 64 20 28 53 51 4c 49 54 45 5f 43    void (SQLITE_C
eb50: 41 4c 4c 42 41 43 4b 20 2a 28 2a 78 44 6c 53 79  ALLBACK *(*xDlSy
eb60: 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  m)(sqlite3_vfs*,
eb70: 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61  void*, const cha
eb80: 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69  r *zSymbol))(voi
eb90: 64 29 3b 0a 20 20 76 6f 69 64 20 28 53 51 4c 49  d);.  void (SQLI
eba0: 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 44 6c  TE_CALLBACK *xDl
ebb0: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
ebc0: 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69  fs*, void*);.  i
ebd0: 6e 74 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42  nt (SQLITE_CALLB
ebe0: 41 43 4b 20 2a 78 52 61 6e 64 6f 6d 6e 65 73 73  ACK *xRandomness
ebf0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ec00: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
ec10: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 53  *zOut);.  int (S
ec20: 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a  QLITE_CALLBACK *
ec30: 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f  xSleep)(sqlite3_
ec40: 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73  vfs*, int micros
ec50: 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28  econds);.  int (
ec60: 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20  SQLITE_CALLBACK 
ec70: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73  *xCurrentTime)(s
ec80: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75  qlite3_vfs*, dou
ec90: 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 53 51  ble*);.  int (SQ
eca0: 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78  LITE_CALLBACK *x
ecb0: 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71  GetLastError)(sq
ecc0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c  lite3_vfs*, int,
ecd0: 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20   char *);.  /*. 
ece0: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
ecf0: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
ed00: 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71  sion 1 of the sq
ed10: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a  lite_vfs object.
ed20: 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e    ** definition.
ed30: 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c    Those that fol
ed40: 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e  low are added in
ed50: 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61   version 2 or la
ed60: 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  ter.  */.  int (
ed70: 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20  SQLITE_CALLBACK 
ed80: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74  *xCurrentTimeInt
ed90: 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  64)(sqlite3_vfs*
eda0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a  , sqlite3_int64*
edb0: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
edc0: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
edd0: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
ede0: 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71   and 2 of the sq
edf0: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
ee00: 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f  .  ** Those belo
ee10: 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f  w are for versio
ee20: 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e  n 3 and greater.
ee30: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 53 51 4c  .  */.  int (SQL
ee40: 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 53  ITE_CALLBACK *xS
ee50: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
ee60: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
ee70: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
ee80: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
ee90: 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73  tr);.  sqlite3_s
eea0: 79 73 63 61 6c 6c 5f 70 74 72 20 28 53 51 4c 49  yscall_ptr (SQLI
eeb0: 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 47 65  TE_CALLBACK *xGe
eec0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
eed0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
eee0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
eef0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 53 51   const char *(SQ
ef00: 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78  LITE_CALLBACK *x
ef10: 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  NextSystemCall)(
ef20: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
ef30: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
ef40: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
ef50: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
ef60: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
ef70: 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65  through 3 of the
ef80: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
ef90: 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65  ct..  ** New fie
efa0: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
efb0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65  ded in future ve
efc0: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
efd0: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
efe0: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
eff0: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
f000: 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a  ppens. .  */.};.
f010: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f020: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
f030: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
f040: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
f050: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
f060: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
f070: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
f080: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
f090: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
f0a0: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
f0b0: 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65  object.  They de
f0c0: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
f0d0: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
f0e0: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
f0f0: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
f100: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
f110: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
f120: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
f130: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
f140: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
f150: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
f160: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
f170: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
f180: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
f190: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
f1a0: 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65  whether the name
f1b0: 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62  d directory is b
f1c0: 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64  oth readable and
f1d0: 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e   writable.** (in
f1e0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66   other words, if
f1f0: 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64   files can be ad
f200: 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e  ded, removed, an
f210: 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e  d renamed within
f220: 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72  .** the director
f230: 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  y)..** The SQLIT
f240: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
f250: 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63  TE constant is c
f260: 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e  urrently used on
f270: 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65  ly by the.** [te
f280: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
f290: 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75  ry pragma], thou
f2a0: 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68  gh this could ch
f2b0: 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
f2c0: 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
f2d0: 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53  QLite..** With S
f2e0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
f2f0: 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  D, the xAccess m
f300: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
f310: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
f320: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54   is readable.  T
f330: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
f340: 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69  _READ constant i
f350: 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75  s.** currently u
f360: 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74  nused, though it
f370: 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69   might be used i
f380: 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61  n a future relea
f390: 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
f3a0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
f3b0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
f3c0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
f3d0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f3e0: 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65  WRITE 1   /* Use
f3f0: 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70  d by PRAGMA temp
f400: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
f410: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
f420: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20  TE_ACCESS_READ  
f430: 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65      2   /* Unuse
f440: 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
f450: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
f460: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53  the xShmLock VFS
f470: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
f480: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
f490: 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65  tants define the
f4a0: 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67   various locking
f4b0: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
f4c0: 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53  llowed by the xS
f4d0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66  hmLock method of
f4e0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
f4f0: 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66  hods].  The.** f
f500: 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65  ollowing are the
f510: 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62   only legal comb
f520: 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67  inations of flag
f530: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d  s to the.** xShm
f540: 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Lock method:.**.
f550: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
f560: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
f570: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
f580: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
f590: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
f5a0: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
f5b0: 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  SIVE.** <li>  SQ
f5c0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
f5d0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
f5e0: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
f5f0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
f600: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
f610: 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  USIVE.** </ul>.*
f620: 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b  *.** When unlock
f630: 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48  ing, the same SH
f640: 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56  ARED or EXCLUSIV
f650: 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73  E flag must be s
f660: 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61  upplied as.** wa
f670: 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63  s given on the c
f680: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63  orresponding loc
f690: 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  k.  .**.** The x
f6a0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63  ShmLock method c
f6b0: 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  an transition be
f6c0: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
f6d0: 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20  nd SHARED or.** 
f6e0: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
f6f0: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20   and EXCLUSIVE. 
f700: 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73   It cannot trans
f710: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48  ition between SH
f720: 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c  ARED.** and EXCL
f730: 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e  USIVE..*/.#defin
f740: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c  e SQLITE_SHM_UNL
f750: 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66  OCK       1.#def
f760: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  ine SQLITE_SHM_L
f770: 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64  OCK         2.#d
f780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
f790: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a  _SHARED       4.
f7a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
f7b0: 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  HM_EXCLUSIVE    
f7c0: 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
f7d0: 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c  F: Maximum xShmL
f7e0: 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20  ock index.**.** 
f7f0: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
f800: 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  hod on [sqlite3_
f810: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20  io_methods] may 
f820: 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65  use values.** be
f830: 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73  tween 0 and this
f840: 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20   upper bound as 
f850: 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67  its "offset" arg
f860: 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51  ument..** The SQ
f870: 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e  Lite core will n
f880: 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20  ever attempt to 
f890: 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61  acquire or relea
f8a0: 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74  se a.** lock out
f8b0: 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e  side of this ran
f8c0: 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge.*/.#define SQ
f8d0: 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20  LITE_SHM_NLOCK  
f8e0: 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20        8.../*.** 
f8f0: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61  CAPI3REF: Initia
f900: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20  lize The SQLite 
f910: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  Library.**.** ^T
f920: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
f930: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
f940: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a  initializes the.
f950: 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  ** SQLite librar
f960: 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  y.  ^The sqlite3
f970: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
f980: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
f990: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
f9a0: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
f9b0: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
f9c0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
f9d0: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
f9e0: 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20  are designed to 
f9f0: 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69  aid in process i
fa00: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
fa10: 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e  d.** shutdown on
fa20: 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
fa30: 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20  s.  Workstation 
fa40: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69  applications usi
fa50: 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72  ng.** SQLite nor
fa60: 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65  mally do not nee
fa70: 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68  d to invoke eith
fa80: 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  er of these rout
fa90: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ines..**.** A ca
faa0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
fab0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
fac0: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
fad0: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l if it is.** th
fae0: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
faf0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fb00: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72  ) is invoked dur
fb10: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
fb20: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
fb30: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
fb40: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
fb50: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fb60: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
fb70: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
fb80: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
fb90: 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c  utdown().  ^(Onl
fba0: 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  y an effective c
fbb0: 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  all.** of sqlite
fbc0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
fbd0: 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69  oes any initiali
fbe0: 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68  zation.  All oth
fbf0: 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20  er calls.** are 
fc00: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
fc10: 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  )^.**.** A call 
fc20: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
fc30: 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66  own() is an "eff
fc40: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
fc50: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  it is the first.
fc60: 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ** call to sqlit
fc70: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69  e3_shutdown() si
fc80: 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c  nce the last sql
fc90: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fca0: 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e  ).  ^(Only.** an
fcb0: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20   effective call 
fcc0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
fcd0: 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64  own() does any d
fce0: 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e  einitialization.
fcf0: 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  .** All other va
fd00: 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  lid calls to sql
fd10: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
fd20: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
fd30: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ops.)^.**.** The
fd40: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fd50: 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ize() interface 
fd60: 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62  is threadsafe, b
fd70: 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ut sqlite3_shutd
fd80: 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e  own().** is not.
fd90: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68    The sqlite3_sh
fda0: 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61  utdown() interfa
fdb0: 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20  ce must only be 
fdc0: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  called from a.**
fdd0: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
fde0: 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62   All open [datab
fdf0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
fe00: 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20   must be closed 
fe10: 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72  and all.** other
fe20: 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65   SQLite resource
fe30: 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f  s must be deallo
fe40: 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69  cated prior to i
fe50: 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  nvoking.** sqlit
fe60: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  e3_shutdown()..*
fe70: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
fe80: 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65   things, ^sqlite
fe90: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77  3_initialize() w
fea0: 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  ill invoke.** sq
feb0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
fec0: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71    Similarly, ^sq
fed0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fee0: 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  .** will invoke 
fef0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
ff00: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
ff10: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ff20: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
ff30: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  s [SQLITE_OK] on
ff40: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66   success..** ^If
ff50: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
ff60: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
ff70: 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65  lize() is unable
ff80: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a   to initialize.*
ff90: 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70  * the library (p
ffa0: 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61  erhaps it is una
ffb0: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
ffc0: 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63  a needed resourc
ffd0: 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d  e such.** as a m
ffe0: 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73  utex) it returns
fff0: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
10000 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
10010 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
10020 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
10030 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
10040 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72   is called inter
10050 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74  nally by many ot
10060 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
10070 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74  terfaces so that
10080 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
10090 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74  usually does not
100a0 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f   need to.** invo
100b0 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
100c0 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
100d0 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
100e0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
100f0 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  .** calls sqlite
10100 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
10110 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
10120 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74  rary will be aut
10130 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e  omatically.** in
10140 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b  itialized when [
10150 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
10160 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20  is called if it 
10170 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69  has not be initi
10180 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64  alized.** alread
10190 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66  y.  ^However, if
101a0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
101b0 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51  led with the [SQ
101c0 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
101d0 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  IT].** compile-t
101e0 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ime option, then
101f0 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63   the automatic c
10200 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
10210 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
10220 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20  are omitted and 
10230 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
10240 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  must call sqlite
10250 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
10260 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72  irectly.** prior
10270 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
10280 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
10290 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d  face.  For maxim
102a0 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a  um portability,.
102b0 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** it is recomme
102c0 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
102d0 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e  ations always in
102e0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
102f0 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72  tialize().** dir
10300 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75  ectly prior to u
10310 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
10320 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
10330 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65    Future release
10340 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d  s.** of SQLite m
10350 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e  ay require this.
10360 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
10370 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65  , the behavior e
10380 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e  xhibited.** when
10390 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
103a0 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
103b0 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20  _OMIT_AUTOINIT] 
103c0 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65  might become the
103d0 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61  .** default beha
103e0 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74  vior in some fut
103f0 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  ure release of S
10400 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
10410 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10420 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
10430 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
10440 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69   specific.** ini
10450 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74  tialization of t
10460 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
10470 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
10480 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74  os_end().** rout
10490 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
104a0 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33  ffect of sqlite3
104b0 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70  _os_init().  Typ
104c0 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65  ical tasks.** pe
104d0 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65  rformed by these
104e0 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64   routines includ
104f0 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20  e allocation or 
10500 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
10510 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72  of static resour
10520 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74  ces, initializat
10530 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61  ion of global va
10540 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74  riables,.** sett
10550 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74  ing up a default
10560 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d   [sqlite3_vfs] m
10570 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e  odule, or settin
10580 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c  g up.** a defaul
10590 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
105a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
105b0 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  onfig()]..**.** 
105c0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
105d0 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76  should never inv
105e0 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74  oke either sqlit
105f0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
10600 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
10610 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54  d() directly.  T
10620 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
10630 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b  hould only invok
10640 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  e.** sqlite3_ini
10650 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71  tialize() and sq
10660 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10670 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
10680 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65  s_init().** inte
10690 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20  rface is called 
106a0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
106b0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
106c0 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c  ize() and.** sql
106d0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73  ite3_os_end() is
106e0 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74   called by sqlit
106f0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
10700 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69  Appropriate.** i
10710 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
10720 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  or sqlite3_os_in
10730 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
10740 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65  _os_end().** are
10750 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
10760 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  te when it is co
10770 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c  mpiled for Unix,
10780 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f   Windows, or OS/
10790 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74  2..** When [cust
107a0 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c  om builds | buil
107b0 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
107c0 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67  forms].** (using
107d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
107e0 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
107f0 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
10800 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
10810 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
10820 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
10830 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
10840 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
10850 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
10860 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
10870 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
10880 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
10890 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
108a0 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
108b0 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
108c0 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
108d0 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
108e0 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
108f0 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
10900 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
10910 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
10920 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71  QLITE_APICALL sq
10930 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10940 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
10950 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50  PI int SQLITE_AP
10960 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 68  ICALL sqlite3_sh
10970 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51  utdown(void);.SQ
10980 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
10990 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69  ITE_APICALL sqli
109a0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64  te3_os_init(void
109b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
109c0 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c  t SQLITE_APICALL
109d0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
109e0 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
109f0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
10a00 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ing The SQLite L
10a10 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65  ibrary.**.** The
10a20 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10a30 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
10a40 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
10a50 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
10a60 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
10a70 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
10a80 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
10a90 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
10aa0 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
10ab0 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
10ac0 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
10ad0 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
10ae0 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
10af0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
10b00 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
10b10 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
10b20 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
10b30 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
10b40 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
10b50 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
10b60 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
10b70 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c  **.** <b>The sql
10b80 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
10b90 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74  terface is not t
10ba0 68 72 65 61 64 73 61 66 65 2e 20 54 68 65 20 61  hreadsafe. The a
10bb0 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
10bc0 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 6e  st ensure that n
10bd0 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
10be0 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
10bf0 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
10c00 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
10c10 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10c20 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e   is running.</b>
10c30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
10c40 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
10c50 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  rface.** may onl
10c60 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69  y be invoked pri
10c70 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e  or to library in
10c80 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69  itialization usi
10c90 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  ng.** [sqlite3_i
10ca0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20  nitialize()] or 
10cb0 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62  after shutdown b
10cc0 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y [sqlite3_shutd
10cd0 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73  own()]..** ^If s
10ce0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10cf0 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
10d00 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
10d10 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72  ize()] and befor
10d20 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  e.** [sqlite3_sh
10d30 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69  utdown()] then i
10d40 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  t will return SQ
10d50 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20  LITE_MISUSE..** 
10d60 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
10d70 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e  hat ^sqlite3_con
10d80 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
10d90 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
10da0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
10db0 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
10dc0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
10dd0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10de0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
10df0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
10e00 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10e10 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
10e20 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  * [configuration
10e30 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
10e40 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
10e50 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
10e60 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
10e70 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
10e80 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
10e90 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
10ea0 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75   on the [configu
10eb0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a  ration option].*
10ec0 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
10ed0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
10ee0 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
10ef0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
10f00 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
10f10 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
10f20 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66  LITE_OK]..** ^If
10f30 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
10f40 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
10f50 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
10f60 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
10f70 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
10f80 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
10f90 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
10fa0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
10fb0 20 69 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43   int SQLITE_CDEC
10fc0 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  L sqlite3_config
10fd0 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  (int, ...);../*.
10fe0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
10ff0 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20  figure database 
11000 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d  connections.** M
11010 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
11020 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
11030 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
11040 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
11050 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
11060 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
11070 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
11080 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
11090 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
110a0 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
110b0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
110c0 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
110d0 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
110e0 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
110f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11100 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
11110 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
11120 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nt)..**.** The s
11130 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
11140 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
11150 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
11160 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
11170 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
11180 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  DE | configurati
11190 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e  on verb] - an in
111a0 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74  teger code .** t
111b0 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
111c0 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  at aspect of the
111d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
111e0 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
111f0 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53  configured..** S
11200 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
11210 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69  nts vary dependi
11220 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67  ng on the config
11230 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a  uration verb..**
11240 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
11250 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
11260 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
11270 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  OK if and only i
11280 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73  f.** the call is
11290 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63   considered succ
112a0 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54  essful..*/.SQLIT
112b0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
112c0 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 64  _CDECL sqlite3_d
112d0 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
112e0 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
112f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11300 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
11310 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a  ion Routines.**.
11320 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
11330 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65  f this object de
11340 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
11350 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69  ace between SQLi
11360 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65  te.** and low-le
11370 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
11380 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a  ation routines..
11390 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  **.** This objec
113a0 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c  t is used in onl
113b0 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74  y one place in t
113c0 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  he SQLite interf
113d0 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ace..** A pointe
113e0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
113f0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
11400 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  is the argument 
11410 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
11420 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68  onfig()] when th
11430 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
11440 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51  option is.** [SQ
11450 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
11460 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  OC] or [SQLITE_C
11470 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
11480 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69  .  .** By creati
11490 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ng an instance o
114a0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a  f this object.**
114b0 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20   and passing it 
114c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
114d0 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
114e0 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64  IG_MALLOC]).** d
114f0 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  uring configurat
11500 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ion, an applicat
11510 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20  ion can specify 
11520 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
11530 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
11540 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f  ion subsystem fo
11550 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20  r SQLite to use 
11560 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a  for all of its.*
11570 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  * dynamic memory
11580 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   needs..**.** No
11590 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  te that SQLite c
115a0 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61  omes with severa
115b0 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  l [built-in memo
115c0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a  ry allocators].*
115d0 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65  * that are perfe
115e0 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f  ctly adequate fo
115f0 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69  r the overwhelmi
11600 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61  ng majority of a
11610 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61  pplications.** a
11620 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a  nd that this obj
11630 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66  ect is only usef
11640 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e  ul to a tiny min
11650 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
11660 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70  tions.** with sp
11670 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79  ecialized memory
11680 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
11690 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20  irements.  This 
116a0 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73  object is.** als
116b0 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  o used during te
116c0 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20  sting of SQLite 
116d0 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63  in order to spec
116e0 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
116f0 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
11700 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75  ocator that simu
11710 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74  lates memory out
11720 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69  -of-memory condi
11730 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65  tions in.** orde
11740 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  r to verify that
11750 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73   SQLite recovers
11760 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d   gracefully from
11770 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69   such.** conditi
11780 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ons..**.** The x
11790 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63  Malloc, xRealloc
117a0 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68  , and xFree meth
117b0 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69  ods must work li
117c0 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63  ke the.** malloc
117d0 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e  (), realloc() an
117e0 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
117f0 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
11800 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
11810 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
11820 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73  ntees that the s
11830 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
11840 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73  o.** xRealloc is
11850 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20   always a value 
11860 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72  returned by a pr
11870 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75  ior call to xRou
11880 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a  ndup..**.** xSiz
11890 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  e should return 
118a0 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
118b0 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61  ze of a memory a
118c0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65  llocation.** pre
118d0 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
118e0 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72   from xMalloc or
118f0 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20   xRealloc.  The 
11900 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a  allocated size.*
11910 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c  * is always at l
11920 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74  east as big as t
11930 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  he requested siz
11940 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  e but may be lar
11950 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ger..**.** The x
11960 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72  Roundup method r
11970 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c  eturns what woul
11980 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74  d be the allocat
11990 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20  ed size of.** a 
119a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
119b0 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63  n given a partic
119c0 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73  ular requested s
119d0 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72  ize.  Most memor
119e0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20  y.** allocators 
119f0 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20  round up memory 
11a00 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c  allocations at l
11a10 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74  east to the next
11a20 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20   multiple.** of 
11a30 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74  8.  Some allocat
11a40 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20  ors round up to 
11a50 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c  a larger multipl
11a60 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20  e or to a power 
11a70 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d  of 2..** Every m
11a80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11a90 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20   request coming 
11aa0 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69  in through [sqli
11ab0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  te3_malloc()].**
11ac0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
11ad0 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61  lloc()] first ca
11ae0 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49  lls xRoundup.  I
11af0 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72  f xRoundup retur
11b00 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63  ns 0, .** that c
11b10 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73  auses the corres
11b20 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61  ponding memory a
11b30 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69  llocation to fai
11b40 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e  l..**.** The xIn
11b50 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61  it method initia
11b60 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  lizes the memory
11b70 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72   allocator.  For
11b80 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
11b90 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
11ba0 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
11bb0 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
11bc0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
11bd0 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
11be0 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
11bf0 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
11c00 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
11c10 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
11c20 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
11c30 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
11c40 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
11c50 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
11c60 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
11c70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
11c80 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
11c90 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
11ca0 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
11cb0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c  **.** SQLite hol
11cc0 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
11cd0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
11ce0 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69  ER] mutex when i
11cf0 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65  t invokes.** the
11d00 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73   xInit method, s
11d10 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  o the xInit meth
11d20 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74  od need not be t
11d30 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a  hreadsafe.  The.
11d40 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  ** xShutdown met
11d50 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c  hod is only call
11d60 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
11d70 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20  _shutdown()] so 
11d80 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e  it does.** not n
11d90 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64  eed to be thread
11da0 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f  safe either.  Fo
11db0 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68  r all other meth
11dc0 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68  ods, SQLite.** h
11dd0 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
11de0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
11df0 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67  M] mutex as long
11e00 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   as the.** [SQLI
11e10 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
11e20 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  TUS] configurati
11e30 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72  on option is tur
11e40 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a  ned on (which.**
11e50 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c   it is by defaul
11e60 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65  t) and so the me
11e70 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61  thods are automa
11e80 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a  tically serializ
11e90 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  ed..** However, 
11ea0 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  if [SQLITE_CONFI
11eb0 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20  G_MEMSTATUS] is 
11ec0 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74  disabled, then t
11ed0 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68  he other.** meth
11ee0 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65  ods must be thre
11ef0 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d  adsafe or else m
11f00 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72  ake their own ar
11f10 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a  rangements for.*
11f20 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e  * serialization.
11f30 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
11f40 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
11f50 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61  xInit() more tha
11f60 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61  n once without a
11f70 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a  n intervening.**
11f80 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f   call to xShutdo
11f90 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  wn()..*/.typedef
11fa0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
11fb0 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
11fc0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
11fd0 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
11fe0 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
11ff0 76 6f 69 64 20 2a 28 53 51 4c 49 54 45 5f 43 41  void *(SQLITE_CA
12000 4c 4c 42 41 43 4b 20 2a 78 4d 61 6c 6c 6f 63 29  LLBACK *xMalloc)
12010 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
12020 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
12030 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
12040 20 20 76 6f 69 64 20 28 53 51 4c 49 54 45 5f 43    void (SQLITE_C
12050 41 4c 4c 42 41 43 4b 20 2a 78 46 72 65 65 29 28  ALLBACK *xFree)(
12060 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
12070 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
12080 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
12090 20 76 6f 69 64 20 2a 28 53 51 4c 49 54 45 5f 43   void *(SQLITE_C
120a0 41 4c 4c 42 41 43 4b 20 2a 78 52 65 61 6c 6c 6f  ALLBACK *xReallo
120b0 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
120c0 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
120d0 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
120e0 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43   (SQLITE_CALLBAC
120f0 4b 20 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29  K *xSize)(void*)
12100 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
12110 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
12120 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
12130 2a 2f 0a 20 20 69 6e 74 20 28 53 51 4c 49 54 45  */.  int (SQLITE
12140 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 52 6f 75 6e  _CALLBACK *xRoun
12150 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
12160 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
12170 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
12180 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
12190 2a 2f 0a 20 20 69 6e 74 20 28 53 51 4c 49 54 45  */.  int (SQLITE
121a0 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 49 6e 69 74  _CALLBACK *xInit
121b0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
121c0 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
121d0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
121e0 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
121f0 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43   (SQLITE_CALLBAC
12200 4b 20 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f  K *xShutdown)(vo
12210 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
12220 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
12230 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
12240 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
12250 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
12260 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
12270 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
12280 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
12290 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
122a0 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
122b0 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  Options.** KEYWO
122c0 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74  RDS: {configurat
122d0 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a  ion option}.**.*
122e0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
122f0 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
12300 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
12310 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12320 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
12330 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
12340 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
12350 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
12360 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
12370 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
12380 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12390 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
123a0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
123b0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
123c0 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
123d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
123e0 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
123f0 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
12400 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
12410 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
12420 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
12430 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
12440 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
12450 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
12460 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
12470 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
12480 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
12490 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
124a0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
124b0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
124c0 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
124d0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
124e0 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
124f0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
12500 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
12510 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64  INGLETHREAD]] <d
12520 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12530 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74  SINGLETHREAD</dt
12540 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
12550 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
12560 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
12570 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
12580 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
12590 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69  ding mode] to Si
125a0 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e  ngle-thread.  In
125b0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
125c0 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
125d0 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
125e0 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
125f0 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
12600 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
12610 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
12620 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c  hread.   ^If SQL
12630 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12640 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
12650 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
12660 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
12670 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
12680 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
12690 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
126a0 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74  ible to change t
126b0 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
126c0 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66  de] from its def
126d0 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  ault.** value of
126e0 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61   Single-thread a
126f0 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nd so [sqlite3_c
12700 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
12710 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  turn .** [SQLITE
12720 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
12730 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
12740 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
12750 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75  HREAD.** configu
12760 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
12770 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12780 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
12790 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
127a0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
127b0 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
127c0 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
127d0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
127e0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
127f0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
12800 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
12810 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72  de] to Multi-thr
12820 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
12830 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
12840 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e  s.** mutexing on
12850 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12860 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
12870 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
12880 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20  objects..** The 
12890 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72  application is r
128a0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73  esponsible for s
128b0 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73  erializing acces
128c0 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73  s to.** [databas
128d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
128e0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
128f0 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f  tements].  But o
12900 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20  ther mutexes.** 
12910 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74  are enabled so t
12920 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
12930 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69  be safe to use i
12940 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
12950 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e  ed.** environmen
12960 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20  t as long as no 
12970 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65  two threads atte
12980 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73  mpt to use the s
12990 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ame.** [database
129a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
129b0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20  the same time.  
129c0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
129d0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
129e0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
129f0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
12a00 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
12a10 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
12a20 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
12a30 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
12a40 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72  et the Multi-thr
12a50 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
12a60 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
12a70 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
12a80 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
12a90 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
12aa0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
12ab0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
12ac0 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67  LTITHREAD config
12ad0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
12ae0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12af0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
12b00 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  LIZED]] <dt>SQLI
12b10 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
12b20 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZED</dt>.** <dd
12b30 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
12b40 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
12b50 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
12b60 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
12b70 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
12b80 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64  e] to Serialized
12b90 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
12ba0 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e  , this option en
12bb0 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
12bc0 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74  exes including t
12bd0 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20  he recursive.** 
12be0 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61  mutexes on [data
12bf0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12c00 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
12c10 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
12c20 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f  s..** In this mo
12c30 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65  de (which is the
12c40 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51   default when SQ
12c50 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12c60 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45   with.** [SQLITE
12c70 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20  _THREADSAFE=1]) 
12c80 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
12c90 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73  ry will itself s
12ca0 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a  erialize access.
12cb0 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20  ** to [database 
12cc0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
12cd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12ce0 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74  ments] so that t
12cf0 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  he.** applicatio
12d00 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65  n is free to use
12d10 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
12d20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12d30 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b  or the.** same [
12d40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12d50 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74  nt] in different
12d60 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
12d70 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49  same time..** ^I
12d80 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
12d90 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
12da0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
12db0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
12dc0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
12dd0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
12de0 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
12df0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
12e00 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20   the Serialized 
12e10 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
12e20 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
12e30 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
12e40 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
12e50 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
12e60 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
12e70 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
12e80 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69  IZED configurati
12e90 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
12ea0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12eb0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c  ONFIG_MALLOC]] <
12ec0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12ed0 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  _MALLOC</dt>.** 
12ee0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
12ef0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
12f00 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
12f10 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
12f20 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f  hich is .** a po
12f30 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
12f40 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
12f50 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12f60 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
12f70 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
12f80 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
12f90 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
12fa0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12fb0 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  n routines to be
12fc0 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f   used in place o
12fd0 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  f.** the memory 
12fe0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
12ff0 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
13000 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65  QLite.)^ ^SQLite
13010 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77   makes.** its ow
13020 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
13030 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  f the content of
13040 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
13050 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
13060 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ture.** before t
13070 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
13080 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72  ig()] call retur
13090 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ns.</dd>.**.** [
130a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
130b0 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  ETMALLOC]] <dt>S
130c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
130d0 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
130e0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
130f0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
13100 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  C option takes a
13110 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13120 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
13130 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
13140 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
13150 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
13160 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
13170 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
13180 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  m_methods].** st
13190 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
131a0 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
131b0 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d  ntly defined mem
131c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
131d0 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
131e0 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
131f0 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
13200 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65  d the default me
13210 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
13220 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
13230 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20   a wrapper that 
13240 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f  simulations memo
13250 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
13260 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63  ilure or.** trac
13270 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c  ks memory usage,
13280 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f   for example. </
13290 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
132a0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
132b0 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TUS]] <dt>SQLITE
132c0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
132d0 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  S</dt>.** <dd> ^
132e0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
132f0 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69  G_MEMSTATUS opti
13300 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
13310 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
13320 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72   int,.** interpr
13330 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
13340 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
13350 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
13360 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a   collection of.*
13370 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
13380 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20  ion statistics. 
13390 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c  ^(When memory al
133a0 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
133b0 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  ics are.** disab
133c0 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69  led, the followi
133d0 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ng SQLite interf
133e0 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d  aces become non-
133f0 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20  operational:.** 
13400 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e    <ul>.**   <li>
13410 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
13420 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c  _used()].**   <l
13430 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
13440 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a  ry_highwater()].
13450 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
13460 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
13470 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  it64()].**   <li
13480 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  > [sqlite3_statu
13490 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  s64()].**   </ul
134a0 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
134b0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
134c0 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
134d0 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
134e0 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
134f0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
13500 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
13510 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
13520 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
13530 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
13540 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
13550 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
13560 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
13570 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13580 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
13590 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
135a0 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
135b0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
135c0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74  NFIG_SCRATCH opt
135d0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
135e0 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
135f0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c  ffer.** that SQL
13600 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20  ite can use for 
13610 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
13620 20 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72   ^(There are thr
13630 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  ee arguments.** 
13640 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
13650 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69  _SCRATCH:  A poi
13660 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
13670 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
13680 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
13690 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61  ch the scratch a
136a0 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  llocations will 
136b0 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65  be.** drawn, the
136c0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
136d0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
136e0 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
136f0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
13700 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f   of scratch allo
13710 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a  cations (N).)^.*
13720 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
13730 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
13740 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
13750 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
13760 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
13770 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
13780 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
13790 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20  te will not use 
137a0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63  more than one sc
137b0 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65  ratch buffers pe
137c0 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51  r thread..** ^SQ
137d0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
137e0 72 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63  request a scratc
137f0 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
13800 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
13810 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
13820 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a  se page size..**
13830 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64   ^If SQLite need
13840 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  s needs addition
13850 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  al.** scratch me
13860 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
13870 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
13880 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
13890 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
138a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
138b0 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
138c0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
138d0 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
138e0 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  <p>.** ^When the
138f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f   application pro
13900 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74  vides any amount
13910 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f   of scratch memo
13920 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49  ry using.** SQLI
13930 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
13940 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73  H, SQLite avoids
13950 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72   unnecessary lar
13960 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  ge.** [sqlite3_m
13970 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63  alloc|heap alloc
13980 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73  ations]..** This
13990 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f   can help [Robso
139a0 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20  n proof|prevent 
139b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
139c0 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20  n failures] due 
139d0 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d  to heap.** fragm
139e0 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d  entation in low-
139f0 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20  memory embedded 
13a00 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64  systems..** </dd
13a10 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13a20 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
13a30 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
13a40 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
13a50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
13a60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13a70 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e  PAGECACHE option
13a80 20 73 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d   specifies a mem
13a90 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74  ory pool.** that
13aa0 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
13ab0 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
13ac0 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
13ad0 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
13ae0 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
13af0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
13b00 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
13b10 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e  on option is a n
13b20 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69  o-op if an appli
13b30 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
13b40 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
13b50 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
13b60 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  aded using the [
13b70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13b80 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72  ACHE2]..** ^Ther
13b90 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
13ba0 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f  ments to SQLITE_
13bb0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
13bc0 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  : A pointer to.*
13bd0 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  * 8-byte aligned
13be0 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20   memory (pMem), 
13bf0 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
13c00 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65   page cache line
13c10 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
13c20 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68  e number of cach
13c30 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20  e lines (N)..** 
13c40 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
13c50 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
13c60 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
13c70 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
13c80 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
13c90 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
13ca0 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73  nd 65536) plus s
13cb0 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20  ome extra bytes 
13cc0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
13cd0 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e   header.  ^The n
13ce0 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62  umber of extra b
13cf0 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74  ytes needed by t
13d00 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a  he page header.*
13d10 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  * can be determi
13d20 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54  ned using [SQLIT
13d30 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
13d40 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69  HDRSZ]..** ^It i
13d50 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
13d60 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
13d70 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72  d memory,.** for
13d80 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65   the sz paramete
13d90 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74  r to be larger t
13da0 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20  han necessary.  
13db0 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75  The pMem.** argu
13dc0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74  ment must be eit
13dd0 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
13de0 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20  er or a pointer 
13df0 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
13e00 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66  aligned block of
13e10 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65   memory of at le
13e20 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20  ast sz*N bytes, 
13e30 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62  otherwise.** sub
13e40 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
13e50 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
13e60 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20  * ^When pMem is 
13e70 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
13e80 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20   will strive to 
13e90 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
13ea0 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61  rovided.** to sa
13eb0 74 69 73 66 79 20 70 61 67 65 20 63 61 63 68 65  tisfy page cache
13ec0 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20   needs, falling 
13ed0 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33  back to [sqlite3
13ee0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a  _malloc()] if.**
13ef0 20 61 20 70 61 67 65 20 63 61 63 68 65 20 6c 69   a page cache li
13f00 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 68 61  ne is larger tha
13f10 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66  n sz bytes or if
13f20 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d   all of the pMem
13f30 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78   buffer.** is ex
13f40 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20  hausted..** ^If 
13f50 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64  pMem is NULL and
13f60 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20   N is non-zero, 
13f70 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62 61  then each databa
13f80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
13f90 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c   does an initial
13fa0 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e   bulk allocation
13fb0 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20   for page cache 
13fc0 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b  memory.** from [
13fd0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13fe0 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72  ] sufficient for
13ff0 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69   N cache lines i
14000 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20  f N is positive 
14010 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e  or.** of -1024*N
14020 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e   bytes if N is n
14030 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61  egative, . ^If a
14040 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67  dditional.** pag
14050 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
14060 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
14070 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
14080 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a   by the initial.
14090 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  ** allocation, t
140a0 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20  hen SQLite goes 
140b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
140c0 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79  oc()] separately
140d0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64   for each.** add
140e0 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69  itional cache li
140f0 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ne. </dd>.**.** 
14100 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14110 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
14120 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
14130 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
14140 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14150 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  AP option specif
14160 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
14170 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74  ory buffer .** t
14180 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
14190 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
141a0 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
141b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
141c0 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f  ds.** beyond tho
141d0 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  se provided for 
141e0 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
141f0 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a  G_SCRATCH] and.*
14200 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
14210 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
14220 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
14230 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69  IG_HEAP option i
14240 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
14250 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
14260 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65  mpiled.** with e
14270 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
14280 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
14290 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
142a0 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74  MEMSYS5] and ret
142b0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
142c0 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65  ERROR] if invoke
142d0 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20  d otherwise..** 
142e0 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  ^There are three
142f0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51   arguments to SQ
14300 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
14310 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61  :.** An 8-byte a
14320 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
14330 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
14340 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
14350 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
14360 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
14370 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
14380 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
14390 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
143a0 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
143b0 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
143c0 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
143d0 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
143e0 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
143f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
14400 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
14410 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
14420 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
14430 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
14440 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
14450 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
14460 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
14470 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
14480 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  ot NULL then the
14490 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
144a0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
144b0 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
144c0 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
144d0 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
144e0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
144f0 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
14500 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
14510 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
14520 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
14530 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
14540 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
14550 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
14560 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
14570 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
14580 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
14590 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
145a0 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
145b0 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
145c0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
145d0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
145e0 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
145f0 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
14600 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
14610 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
14620 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
14630 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
14640 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14650 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b  MUTEX option tak
14660 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14670 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a  ment which is a.
14680 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
14690 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
146a0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
146b0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
146c0 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
146d0 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c  ent specifies al
146e0 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
146f0 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
14700 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a  es to be used.**
14710 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75   in place the mu
14720 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
14730 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
14740 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
14750 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
14760 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
14770 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
14780 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
14790 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61  re before the ca
147a0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
147b0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75  3_config()] retu
147c0 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  rns. ^If SQLite 
147d0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
147e0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
147f0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
14800 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
14810 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
14820 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
14830 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
14840 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
14850 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
14860 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
14870 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
14880 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
14890 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
148a0 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66  ONFIG_MUTEX conf
148b0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
148c0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
148d0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
148e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
148f0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14900 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
14910 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
14920 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
14930 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14940 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f  G_GETMUTEX optio
14950 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14960 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
14970 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
14980 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
14990 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
149a0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
149b0 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
149c0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
149d0 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
149e0 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
149f0 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
14a00 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
14a10 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
14a20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
14a30 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
14a40 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
14a50 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
14a60 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
14a70 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
14a80 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
14a90 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
14aa0 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
14ab0 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
14ac0 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49  or example.   ^I
14ad0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
14ae0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
14af0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
14b00 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
14b10 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
14b20 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
14b30 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
14b40 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
14b50 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
14b60 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
14b70 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
14b80 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
14b90 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
14ba0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14bb0 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  ETMUTEX configur
14bc0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
14bd0 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
14be0 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
14bf0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14c00 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14c10 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14c20 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
14c30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
14c40 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14c50 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e  LOOKASIDE option
14c60 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
14c70 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
14c80 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75  ine.** the defau
14c90 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61  lt size of looka
14ca0 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65  side memory on e
14cb0 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ach [database co
14cc0 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  nnection]..** Th
14cd0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14ce0 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
14cf0 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
14d00 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
14d10 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
14d20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
14d30 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
14d40 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
14d50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
14d60 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   ^(SQLITE_CONFIG
14d70 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65  _LOOKASIDE.** se
14d80 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c  ts the <i>defaul
14d90 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
14da0 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
14db0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
14dc0 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20  SIDE].** option 
14dd0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
14de0 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
14df0 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
14e00 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
14e10 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
14e20 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
14e30 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
14e40 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14e50 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
14e60 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14e70 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
14e80 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14e90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14ea0 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  HE2 option takes
14eb0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14ec0 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
14ed0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14ee0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
14ef0 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
14f00 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
14f10 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
14f20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63  interface to a c
14f30 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
14f40 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
14f50 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61  )^.** ^SQLite ma
14f60 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
14f70 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  e [sqlite3_pcach
14f80 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
14f90 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ct.</dd>.**.** [
14fa0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
14fb0 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  ETPCACHE2]] <dt>
14fc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14fd0 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  TPCACHE2</dt>.**
14fe0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
14ff0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
15000 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
15010 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
15020 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
15030 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
15040 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
15050 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
15060 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
15070 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65   of.** the curre
15080 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  nt page cache im
15090 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
150a0 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
150b0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
150c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
150d0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
150e0 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
150f0 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
15100 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
15110 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  on is used to co
15120 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69  nfigure the SQLi
15130 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72  te.** global [er
15140 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54  ror log]..** (^T
15150 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15160 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
15170 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
15180 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
15190 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
151a0 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
151b0 65 20 6f 66 20 76 6f 69 64 28 53 51 4c 49 54 45  e of void(SQLITE
151c0 5f 43 41 4c 4c 42 41 43 4b 20 2a 29 28 76 6f 69  _CALLBACK *)(voi
151d0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
151e0 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
151f0 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
15200 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
15210 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
15220 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
15230 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
15240 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
15250 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
15260 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
15270 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
15280 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
15290 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
152a0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
152b0 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
152c0 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
152d0 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
152e0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
152f0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
15300 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
15310 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
15320 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
15330 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
15340 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
15350 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
15360 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
15370 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
15380 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
15390 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
153a0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
153b0 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
153c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
153d0 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
153e0 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
153f0 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
15400 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
15410 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
15420 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
15430 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
15440 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
15450 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
15460 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
15470 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
15480 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
15490 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
154a0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
154b0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
154c0 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
154d0 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
154e0 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
154f0 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
15500 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
15510 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
15520 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
15530 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
15540 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
15550 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
15560 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
15570 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
15580 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
15590 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
155a0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
155b0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
155c0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
155d0 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68  _URI.** <dd>^(Th
155e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
155f0 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  URI option takes
15600 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
15610 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a  nt of type int..
15620 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  ** If non-zero, 
15630 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
15640 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
15650 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
15660 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
15670 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e  .** then URI han
15680 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
15690 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49  y disabled.)^ ^I
156a0 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  f URI handling i
156b0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e  s globally.** en
156c0 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
156d0 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b  ames passed to [
156e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
156f0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
15700 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
15710 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
15720 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
15730 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
15740 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
15750 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
15760 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
15770 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
15780 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
15790 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
157a0 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
157b0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
157c0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
157d0 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
157e0 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
157f0 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
15800 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
15810 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
15820 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
15830 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
15840 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
15850 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
15860 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74  ed. ^(By default
15870 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
15880 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
15890 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
158a0 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
158b0 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
158c0 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
158d0 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
158e0 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
158f0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d.)^.**.** [[SQL
15900 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
15910 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
15920 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15930 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
15940 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54  X_SCAN.** <dd>^T
15950 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15960 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
15970 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65  SCAN option take
15980 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67  s a single integ
15990 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77  er.** argument w
159a0 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65  hich is interpre
159b0 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
159c0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61   in order to ena
159d0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a  ble or disable.*
159e0 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  * the use of cov
159f0 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
15a00 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
15a10 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  ns in the query 
15a20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54  optimizer..** ^T
15a30 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
15a40 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64  ng is determined
15a50 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49  .** by the [SQLI
15a60 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e  TE_ALLOW_COVERIN
15a70 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f  G_INDEX_SCAN] co
15a80 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
15a90 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a  n, or is "on".**
15aa0 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65   if that compile
15ab0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
15ac0 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20  omitted..** The 
15ad0 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62  ability to disab
15ae0 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
15af0 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
15b00 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
15b10 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73  ans.** is becaus
15b20 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74  e some incorrect
15b30 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20  ly coded legacy 
15b40 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67  applications mig
15b50 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a  ht malfunction.*
15b60 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d  * when the optim
15b70 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  ization is enabl
15b80 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74  ed.  Providing t
15b90 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a  he ability to.**
15ba0 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74   disable the opt
15bb0 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73  imization allows
15bc0 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67   the older, bugg
15bd0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  y application co
15be0 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  de to work.** wi
15bf0 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65  thout change eve
15c00 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72  n with newer ver
15c10 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
15c20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15c30 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
15c40 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15c50 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c  GETPCACHE]].** <
15c60 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15c70 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49  _PCACHE and SQLI
15c80 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
15c90 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
15ca0 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
15cb0 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
15cc0 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
15cd0 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
15ce0 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
15cf0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
15d00 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
15d10 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
15d20 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
15d30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
15d40 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  QLLOG]].** <dt>S
15d50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
15d60 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  LOG.** <dd>This 
15d70 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
15d80 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69  vailable if sqli
15d90 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
15da0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
15db0 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
15dc0 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
15dd0 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54  macro defined. T
15de0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15df0 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61  t should.** be a
15e00 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75   pointer to a fu
15e10 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76  nction of type v
15e20 6f 69 64 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42  oid(SQLITE_CALLB
15e30 41 43 4b 20 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  ACK *)(void*,sql
15e40 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72  ite3*,const char
15e50 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20  *, int)..** The 
15e60 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65  second should be
15e70 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29   of type (void*)
15e80 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  . The callback i
15e90 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65  s invoked by the
15ea0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74   library.** in t
15eb0 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69  hree separate ci
15ec0 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65  rcumstances, ide
15ed0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76  ntified by the v
15ee0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
15ef0 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
15f00 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66  ameter. If the f
15f10 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
15f20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64  is 0, then the d
15f30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15f40 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  on.** passed as 
15f50 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
15f60 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65  ent has just bee
15f70 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68  n opened. The th
15f80 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
15f90 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66  points to a buff
15fa0 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  er containing th
15fb0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61  e name of the ma
15fc0 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
15fd0 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72  . If the.** four
15fe0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
15ff0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
16000 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74  statement that t
16010 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
16020 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  er.** points to 
16030 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78  has just been ex
16040 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74  ecuted. Or, if t
16050 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
16060 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a  ter is 2, then.*
16070 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  * the connection
16080 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73   being passed as
16090 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
160a0 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63  meter is being c
160b0 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68  losed. The.** th
160c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
160d0 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20   passed NULL In 
160e0 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65  this case.  An e
160f0 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20  xample of using 
16100 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  this.** configur
16110 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e  ation option can
16120 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20   be seen in the 
16130 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20  "test_sqllog.c" 
16140 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a  source file in.*
16150 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20  * the canonical 
16160 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72  SQLite source tr
16170 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ee.</dd>.**.** [
16180 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
16190 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  MAP_SIZE]].** <d
161a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
161b0 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  MMAP_SIZE.** <dd
161c0 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  >^SQLITE_CONFIG_
161d0 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20  MMAP_SIZE takes 
161e0 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67  two 64-bit integ
161f0 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  er (sqlite3_int6
16200 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  4) values.** tha
16210 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c  t are the defaul
16220 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  t mmap size limi
16230 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73  t (the default s
16240 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50  etting for.** [P
16250 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
16260 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  ) and the maximu
16270 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
16280 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54  ize limit..** ^T
16290 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
162a0 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  ng can be overri
162b0 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74  dden by each dat
162c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
162d0 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72   using.** either
162e0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61   the [PRAGMA mma
162f0 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c  p_size] command,
16300 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65   or by using the
16310 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
16320 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
16330 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68  e control.  ^(Th
16340 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
16350 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77  d mmap size.** w
16360 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20  ill be silently 
16370 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63  truncated if nec
16380 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69  essary so that i
16390 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65  t does not excee
163a0 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d the.** compile
163b0 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d  -time maximum mm
163c0 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74  ap size set by t
163d0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  he.** [SQLITE_MA
163e0 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d  X_MMAP_SIZE] com
163f0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
16400 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65  .)^.** ^If eithe
16410 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
16420 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
16430 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
16440 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
16450 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
16460 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
16470 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ult..**.** [[SQL
16480 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
16490 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  _HEAPSIZE]].** <
164a0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
164b0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a  _WIN32_HEAPSIZE.
164c0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
164d0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
164e0 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20  HEAPSIZE option 
164f0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
16500 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a  e if SQLite is.*
16510 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57  * compiled for W
16520 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20  indows with the 
16530 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41  [SQLITE_WIN32_MA
16540 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOC] pre-proces
16550 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66  sor macro.** def
16560 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f  ined. ^SQLITE_CO
16570 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
16580 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62  IZE takes a 32-b
16590 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
165a0 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61  ger value.** tha
165b0 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
165c0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
165d0 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70  the created heap
165e0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
165f0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
16600 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  DRSZ]].** <dt>SQ
16610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
16620 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e  HE_HDRSZ.** <dd>
16630 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
16640 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
16650 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
16660 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
16670 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
16680 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
16690 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69  ger and writes i
166a0 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72  nto that integer
166b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
166c0 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65  xtra.** bytes pe
166d0 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20  r page required 
166e0 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e  for each page in
166f0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
16700 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
16710 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74  he amount of ext
16720 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65  ra space require
16730 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70  d can change dep
16740 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
16750 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65  mpiler,.** targe
16760 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20  t platform, and 
16770 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a  SQLite version..
16780 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16790 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a  ONFIG_PMASZ]].**
167a0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
167b0 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e  IG_PMASZ.** <dd>
167c0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
167d0 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20  IG_PMASZ option 
167e0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
167f0 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
16800 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  * is an unsigned
16810 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74   integer and set
16820 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50  s the "Minimum P
16830 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65  MA Size" for the
16840 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a   multithreaded.*
16850 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74  * sorter to that
16860 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64   integer.  The d
16870 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50  efault minimum P
16880 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62  MA Size is set b
16890 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
168a0 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63  _SORTER_PMASZ] c
168b0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
168c0 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73  on.  New threads
168d0 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a   are launched.**
168e0 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f   to help with so
168f0 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68  rt operations wh
16900 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  en multithreaded
16910 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65   sorting.** is e
16920 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68  nabled (using th
16930 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64  e [PRAGMA thread
16940 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20  s] command) and 
16950 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f  the amount of co
16960 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73  ntent.** to be s
16970 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68  orted exceeds th
16980 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65  e page size time
16990 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66  s the minimum of
169a0 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   the.** [PRAGMA 
169b0 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74  cache_size] sett
169c0 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c  ing and this val
169d0 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ue..**.** [[SQLI
169e0 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
169f0 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64  NL_SPILL]].** <d
16a00 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
16a10 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a  STMTJRNL_SPILL.*
16a20 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
16a30 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
16a40 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74  L_SPILL option t
16a50 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61  akes a single pa
16a60 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a  rameter which.**
16a70 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73 74   becomes the [st
16a80 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d  atement journal]
16a90 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74   spill-to-disk t
16aa0 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b  hreshold.  .** [
16ab0 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  Statement journa
16ac0 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e 20  ls] are held in 
16ad0 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68 65  memory until the
16ae0 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74 65  ir size (in byte
16af0 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74 68  s).** exceeds th
16b00 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61 74  is threshold, at
16b10 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68 65   which point the
16b20 79 20 61 72 65 20 77 72 69 74 74 65 6e 20 74 6f  y are written to
16b30 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20   disk..** Or if 
16b40 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69 73  the threshold is
16b50 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a   -1, statement j
16b60 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77 61  ournals are alwa
16b70 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75  ys held.** exclu
16b80 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79  sively in memory
16b90 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20  ..** Since many 
16ba0 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  statement journa
16bb0 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65 20  ls never become 
16bc0 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20 74  large, setting t
16bd0 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65  he spill.** thre
16be0 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75 65  shold to a value
16bf0 20 73 75 63 68 20 61 73 20 36 34 4b 69 42 20 63   such as 64KiB c
16c00 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75 63  an greatly reduc
16c10 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a  e the amount of.
16c20 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64 20  ** I/O required 
16c30 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74 65  to support state
16c40 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  ment rollback..*
16c50 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  * The default va
16c60 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73 65 74  lue for this set
16c70 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c  ting is controll
16c80 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  ed by the.** [SQ
16c90 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  LITE_STMTJRNL_SP
16ca0 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ILL] compile-tim
16cb0 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64  e option..** </d
16cc0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
16cd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
16ce0 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
16cf0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
16d00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
16d10 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
16d20 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
16d30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
16d40 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
16d50 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
16d60 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16d70 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
16d80 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
16d90 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
16da0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16db0 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
16dc0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
16dd0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
16de0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16df0 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
16e00 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   6  /* void*, in
16e10 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
16e20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16e30 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
16e40 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
16e50 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
16e60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16e70 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
16e80 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
16e90 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
16ea0 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
16eb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
16ec0 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
16ed0 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
16ee0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16ef0 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
16f00 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
16f10 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
16f20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16f30 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
16f40 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
16f50 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
16f60 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73  * */./* previous
16f70 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ly SQLITE_CONFIG
16f80 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77  _CHUNKALLOC 12 w
16f90 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73  hich is now unus
16fa0 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20  ed. */ .#define 
16fb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
16fc0 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f  OKASIDE    13  /
16fd0 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
16fe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16ff0 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20  IG_PCACHE       
17000 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  14  /* no-op */.
17010 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17020 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20  ONFIG_GETPCACHE 
17030 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20     15  /* no-op 
17040 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17050 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20  E_CONFIG_LOG    
17060 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75        16  /* xFu
17070 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65  nc, void* */.#de
17080 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17090 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  IG_URI          
170a0 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  17  /* int */.#d
170b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
170c0 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20  FIG_PCACHE2     
170d0 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   18  /* sqlite3_
170e0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
170f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17100 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
17110 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71  CHE2   19  /* sq
17120 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
17130 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
17140 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17150 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
17160 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a  CAN 20  /* int *
17170 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17180 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20  _CONFIG_SQLLOG  
17190 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c       21  /* xSql
171a0 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64  log, void* */.#d
171b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
171c0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  FIG_MMAP_SIZE   
171d0 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   22  /* sqlite3_
171e0 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69  int64, sqlite3_i
171f0 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt64 */.#define 
17200 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
17210 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20  N32_HEAPSIZE    
17220 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79    23  /* int nBy
17230 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
17240 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17250 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20 20  HE_HDRSZ        
17260 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20  24  /* int *psz 
17270 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17280 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20  E_CONFIG_PMASZ  
17290 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
172a0 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74   /* unsigned int
172b0 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e   szPma */.#defin
172c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
172d0 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20  STMTJRNL_SPILL  
172e0 20 20 20 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e      26  /* int n
172f0 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  Byte */../*.** C
17300 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
17310 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e  e Connection Con
17320 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
17330 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
17340 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
17350 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
17360 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
17370 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
17380 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
17390 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
173a0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
173b0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
173c0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
173d0 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
173e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
173f0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
17400 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
17410 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
17420 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
17430 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
17440 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
17450 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
17460 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
17470 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
17480 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
17490 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
174a0 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
174b0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
174c0 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
174d0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
174e0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
174f0 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
17500 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
17510 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
17520 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
17530 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
17540 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
17550 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
17560 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
17570 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
17580 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
17590 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
175a0 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
175b0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
175c0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
175d0 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
175e0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
175f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
17600 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
17610 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54  nnection]..** ^T
17620 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17630 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
17640 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
17650 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
17660 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
17670 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66  to a memory buff
17680 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f  er to use for lo
17690 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a  okaside memory..
176a0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
176b0 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65  gument after the
176c0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
176d0 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a  _LOOKASIDE verb.
176e0 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69  ** may be NULL i
176f0 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c  n which case SQL
17700 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74  ite will allocat
17710 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69  e the.** lookasi
17720 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66  de buffer itself
17730 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
17740 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20  malloc()]. ^The 
17750 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
17760 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
17770 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
17780 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e   buffer slot.  ^
17790 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
177a0 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nt is the number
177b0 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54   of.** slots.  T
177c0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
177d0 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72  uffer in the fir
177e0 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
177f0 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e   be greater than
17800 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  .** or equal to 
17810 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74  the product of t
17820 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
17830 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  ird arguments.  
17840 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75  The buffer.** mu
17850 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
17860 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
17870 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65  ary.  ^If the se
17880 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
17890 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  .** SQLITE_DBCON
178a0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73  FIG_LOOKASIDE is
178b0 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20   not a multiple 
178c0 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65  of 8, it is inte
178d0 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65  rnally.** rounde
178e0 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65  d down to the ne
178f0 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69  xt smaller multi
17900 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65  ple of 8.  ^(The
17910 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
17920 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  y.** configurati
17930 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  on for a databas
17940 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e  e connection can
17950 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64   only be changed
17960 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f   when that.** co
17970 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  nnection is not 
17980 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20  currently using 
17990 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
179a0 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f  , or in other wo
179b0 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  rds.** when the 
179c0 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20  "current value" 
179d0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
179e0 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75  sqlite3_db_statu
179f0 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e  s](D,[SQLITE_CON
17a00 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e  FIG_LOOKASIDE],.
17a10 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20  ..) is zero..** 
17a20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
17a30 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
17a40 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69  ide memory confi
17a50 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f  guration when lo
17a60 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72  okaside.** memor
17a70 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76  y is in use leav
17a80 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  es the configura
17a90 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61  tion unchanged a
17aa0 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  nd returns .** [
17ab0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c  SQLITE_BUSY].)^<
17ac0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
17ad0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
17ae0 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a  NABLE_FKEY</dt>.
17af0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
17b00 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
17b10 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
17b20 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e  e the enforcemen
17b30 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  t of.** [foreign
17b40 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
17b50 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64  ].  There should
17b60 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
17b70 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
17b80 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
17b90 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
17ba0 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
17bb0 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72  disable FK enfor
17bc0 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74  cement,.** posit
17bd0 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b  ive to enable FK
17be0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20   enforcement or 
17bf0 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
17c00 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
17c10 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20  .** unchanged.  
17c20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17c30 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
17c40 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
17c50 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
17c60 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
17c70 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
17c80 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  her FK enforceme
17c90 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a  nt is off or on.
17ca0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
17cb0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
17cc0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
17cd0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
17ce0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
17cf0 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66   case the FK enf
17d00 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67  orcement setting
17d10 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
17d20 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
17d30 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
17d40 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
17d50 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  IGGER</dt>.** <d
17d60 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
17d70 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
17d80 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52  e or disable [CR
17d90 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
17da0 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65  riggers]..** The
17db0 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
17dc0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
17dd0 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
17de0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
17df0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
17e00 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
17e10 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f   triggers,.** po
17e20 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
17e30 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67   triggers or neg
17e40 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
17e50 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
17e60 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
17e70 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
17e80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17e90 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
17ea0 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
17eb0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
17ec0 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69  cate whether tri
17ed0 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c  ggers are disabl
17ee0 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
17ef0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
17f00 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
17f10 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
17f20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
17f30 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
17f40 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ase the trigger 
17f50 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
17f60 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
17f70 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
17f80 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
17f90 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49  ABLE_FTS3_TOKENI
17fa0 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZER</dt>.** <dd>
17fb0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
17fc0 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
17fd0 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 74  or disable the t
17fe0 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  wo-argument.** v
17ff0 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b 66  ersion of the [f
18000 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d  ts3_tokenizer()]
18010 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63 68 20   function which 
18020 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  is part of the.*
18030 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65  * [FTS3] full-te
18040 78 74 20 73 65 61 72 63 68 20 65 6e 67 69 6e 65  xt search engine
18050 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54   extension..** T
18060 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
18070 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
18080 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
18090 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
180a0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
180b0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
180c0 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65  le fts3_tokenize
180d0 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69  r() or.** positi
180e0 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 66 74 73  ve to enable fts
180f0 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72  3_tokenizer() or
18100 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
18110 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  ve the setting.*
18120 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  * unchanged..** 
18130 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
18140 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
18150 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
18160 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
18170 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
18180 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
18190 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  her fts3_tokeniz
181a0 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f  er is disabled o
181b0 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
181c0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
181d0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
181e0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
181f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
18200 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
18210 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20  the new setting 
18220 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
18230 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
18240 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
18250 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41  ONFIG_ENABLE_LOA
18260 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e  D_EXTENSION</dt>
18270 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
18280 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
18290 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
182a0 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
182b0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
182c0 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ].** interface i
182d0 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20  ndependently of 
182e0 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73  the [load_extens
182f0 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e 63 74  ion()] SQL funct
18300 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ion..** The [sql
18310 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
18320 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50  _extension()] AP
18330 49 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  I enables or dis
18340 61 62 6c 65 73 20 62 6f 74 68 20 74 68 65 0a 2a  ables both the.*
18350 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69 74 65 33  * C-API [sqlite3
18360 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
18370 29 5d 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66  )] and the SQL f
18380 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78  unction [load_ex
18390 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54  tension()]..** T
183a0 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
183b0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
183c0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e  guments..** When
183d0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
183e0 65 6e 74 20 74 6f 20 74 68 69 73 20 69 6e 74 65  ent to this inte
183f0 72 66 61 63 65 20 69 73 20 31 2c 20 74 68 65 6e  rface is 1, then
18400 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50 49 20   only the C-API 
18410 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e  is.** enabled an
18420 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
18430 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69 73 61 62  on remains disab
18440 6c 65 64 2e 20 20 49 66 20 74 68 65 20 66 69 72  led.  If the fir
18450 73 74 20 61 72 67 6d 65 6e 74 20 74 6f 0a 2a 2a  st argment to.**
18460 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
18470 69 73 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20  is 0, then both 
18480 74 68 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68  the C-API and th
18490 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61  e SQL function a
184a0 72 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20  re disabled..** 
184b0 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67  If the first arg
184c0 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65  ument is -1, the
184d0 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65  n no changes are
184e0 20 6d 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f   made to state o
184f0 66 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20  f either the.** 
18500 43 2d 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c  C-API or the SQL
18510 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
18520 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18530 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
18540 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
18550 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
18560 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
18570 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
18580 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  r [sqlite3_load_
18590 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74  extension()] int
185a0 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73  erface.** is dis
185b0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
185c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
185d0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
185e0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a  d parameter may.
185f0 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ** be a NULL poi
18600 6e 74 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63  nter, in which c
18610 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74  ase the new sett
18620 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
18630 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64  ted back..** </d
18640 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
18650 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18660 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
18670 49 44 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IDE             
18680 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e  1001 /* void* in
18690 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
186a0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
186b0 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20  _ENABLE_FKEY    
186c0 20 20 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69         1002 /* i
186d0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
186e0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
186f0 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
18700 52 20 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a  R        1003 /*
18710 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
18720 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
18730 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33  NFIG_ENABLE_FTS3
18740 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20  _TOKENIZER 1004 
18750 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
18760 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
18770 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f  CONFIG_ENABLE_LO
18780 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30  AD_EXTENSION 100
18790 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  5 /* int int* */
187a0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
187b0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
187c0 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
187d0 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45  sult Codes.** ME
187e0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
187f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18800 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
18810 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65  _codes() routine
18820 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
18830 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74  bles the.** [ext
18840 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
18850 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53  es] feature of S
18860 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65  QLite. ^The exte
18870 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  nded result.** c
18880 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65  odes are disable
18890 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72  d by default for
188a0 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70   historical comp
188b0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51  atibility..*/.SQ
188c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
188d0 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69  ITE_APICALL sqli
188e0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
188f0 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
18900 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
18910 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18920 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
18930 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  id.** METHOD: sq
18940 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  lite3.**.** ^Eac
18950 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20  h entry in most 
18960 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65  SQLite tables (e
18970 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f  xcept for [WITHO
18980 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
18990 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75  ).** has a uniqu
189a0 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
189b0 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
189c0 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
189d0 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
189e0 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
189f0 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
18a00 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
18a10 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
18a20 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
18a30 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
18a40 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
18a50 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
18a60 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
18a70 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
18a80 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
18a90 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
18aa0 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
18ab0 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
18ac0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
18ad0 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
18ae0 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
18af0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
18b00 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
18b10 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63  owid(D) interfac
18b20 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
18b30 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a  owid] of the .**
18b40 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
18b50 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
18b60 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61   into a rowid ta
18b70 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20  ble or [virtual 
18b80 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74  table].** on dat
18b90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18ba0 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20   D..** ^Inserts 
18bb0 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f  into [WITHOUT RO
18bc0 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20  WID] tables are 
18bd0 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a  not recorded..**
18be0 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
18bf0 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74  ul [INSERT]s int
18c00 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a  o rowid tables.*
18c10 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
18c20 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61  rred on the data
18c30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18c40 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  D, .** then sqli
18c50 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
18c60 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73  rowid(D) returns
18c70 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49   zero..**.** ^(I
18c80 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
18c90 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
18ca0 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20  igger or within 
18cb0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
18cc0 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65  ].** method, the
18cd0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
18ce0 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b  ill return the [
18cf0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
18d00 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73  serted.** row as
18d10 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
18d20 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
18d30 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20  table method is 
18d40 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
18d50 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
18d60 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
18d70 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74  e method ends, t
18d80 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
18d90 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
18da0 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
18db0 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
18dc0 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
18dd0 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  or virtual.** ta
18de0 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e  ble method began
18df0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
18e00 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
18e10 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
18e20 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
18e30 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
18e40 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
18e50 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
18e60 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
18e70 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
18e80 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
18e90 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
18ea0 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
18eb0 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
18ec0 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
18ed0 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
18ee0 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
18ef0 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
18f00 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
18f10 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
18f20 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
18f30 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
18f40 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
18f50 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
18f60 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
18f70 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
18f80 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
18f90 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
18fa0 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
18fb0 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
18fc0 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
18fd0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
18fe0 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
18ff0 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
19000 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
19010 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
19020 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
19030 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
19040 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
19050 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
19060 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
19070 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
19080 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
19090 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
190a0 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
190b0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
190c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
190d0 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
190e0 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
190f0 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
19100 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
19110 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
19120 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
19130 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
19140 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
19150 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
19160 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
19170 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
19180 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
19190 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
191a0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
191b0 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
191c0 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
191d0 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
191e0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
191f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
19200 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
19210 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
19220 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
19230 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
19240 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
19250 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
19260 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
19270 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
19280 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f  e3_int64 SQLITE_
19290 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  APICALL sqlite3_
192a0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
192b0 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
192c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
192d0 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
192e0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
192f0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
19300 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
19310 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
19320 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
19330 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73  ws modified, ins
19340 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65  erted or.** dele
19350 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
19360 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
19370 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
19380 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  E or DELETE.** s
19390 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20  tatement on the 
193a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
193b0 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79  ion specified by
193c0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
193d0 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69  ter..** ^Executi
193e0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
193f0 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
19400 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69  nt does not modi
19410 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  fy the value.** 
19420 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
19430 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
19440 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d   ^Only changes m
19450 61 64 65 20 64 69 72 65 63 74 6c 79 20 62 79 20  ade directly by 
19460 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41  the INSERT, UPDA
19470 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
19480 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f  tement are.** co
19490 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c  nsidered - auxil
194a0 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
194b0 73 65 64 20 62 79 20 5b 43 52 45 41 54 45 20 54  sed by [CREATE T
194c0 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
194d0 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  s], .** [foreign
194e0 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72   key actions] or
194f0 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
19500 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
19510 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
19520 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73  ..** .** Changes
19530 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
19540 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20  are intercepted 
19550 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20  by .** [INSTEAD 
19560 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53  OF trigger | INS
19570 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73  TEAD OF triggers
19580 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
19590 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a  d. ^The value .*
195a0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
195b0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
195c0 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65  immediately afte
195d0 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  r an INSERT, UPD
195e0 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54  ATE or .** DELET
195f0 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20  E statement run 
19600 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c 77  on a view is alw
19610 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63  ays zero. Only c
19620 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72  hanges made to r
19630 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61  eal .** tables a
19640 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
19650 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72  * Things are mor
19660 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66  e complicated if
19670 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
19680 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
19690 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77  is.** executed w
196a0 68 69 6c 65 20 61 20 74 72 69 67 67 65 72 20 70  hile a trigger p
196b0 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e  rogram is runnin
196c0 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70 70  g. This may happ
196d0 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f  en if the.** pro
196e0 67 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63  gram uses the [c
196f0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
19700 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f  ction], or if so
19710 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63  me other callbac
19720 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e  k.** function in
19730 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68  vokes sqlite3_ch
19740 61 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c 79  anges() directly
19750 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a  . Essentially:.*
19760 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  * .** <ul>.**   
19770 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e  <li> ^(Before en
19780 74 65 72 69 6e 67 20 61 20 74 72 69 67 67 65 72  tering a trigger
19790 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c   program the val
197a0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ue returned by.*
197b0 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33  *        sqlite3
197c0 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
197d0 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66  ion is saved. Af
197e0 74 65 72 20 74 68 65 20 74 72 69 67 67 65 72 20  ter the trigger 
197f0 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20  program .**     
19800 20 20 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c     has finished,
19810 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61   the original va
19820 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e  lue is restored.
19830 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e  )^.** .**   <li>
19840 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69 67   ^(Within a trig
19850 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68  ger program each
19860 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
19870 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20  and DELETE .**  
19880 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20        statement 
19890 73 65 74 73 20 74 68 65 20 76 61 6c 75 65 20 72  sets the value r
198a0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
198b0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
198c0 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d          upon com
198d0 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61  pletion as norma
198e0 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68  l. Of course, th
198f0 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f  is value will no
19900 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20  t include .**   
19910 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73       any changes
19920 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75   performed by su
19930 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20 74  b-triggers, as t
19940 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
19950 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
19960 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61  value will be sa
19970 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64  ved and restored
19980 20 61 66 74 65 72 20 65 61 63 68 20 73 75 62 2d   after each sub-
19990 74 72 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e  trigger has run.
199a0 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a  )^.** </ul>.** .
199b0 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74  ** ^This means t
199c0 68 61 74 20 69 66 20 74 68 65 20 63 68 61 6e 67  hat if the chang
199d0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
199e0 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69  n (or similar) i
199f0 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65  s used.** by the
19a00 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55   first INSERT, U
19a10 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
19a20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
19a30 20 61 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a   a trigger, it .
19a40 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  ** returns the v
19a50 61 6c 75 65 20 61 73 20 73 65 74 20 77 68 65 6e  alue as set when
19a60 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61   the calling sta
19a70 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65  tement began exe
19a80 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69  cuting..** ^If i
19a90 74 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  t is used by the
19aa0 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65   second or subse
19ab0 71 75 65 6e 74 20 73 75 63 68 20 73 74 61 74 65  quent such state
19ac0 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72  ment within a tr
19ad0 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61  igger .** progra
19ae0 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  m, the value ret
19af0 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74  urned reflects t
19b00 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
19b10 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68  s modified by th
19b20 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49  e .** previous I
19b30 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
19b40 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
19b50 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
19b60 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a  e trigger..**.**
19b70 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
19b80 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
19b90 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
19ba0 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
19bb0 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
19bc0 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
19bd0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
19be0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
19bf0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
19c00 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
19c10 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
19c20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
19c30 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
19c40 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
19c50 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
19c60 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
19c70 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
19c80 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
19c90 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
19ca0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50  PI int SQLITE_AP
19cb0 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 68  ICALL sqlite3_ch
19cc0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
19cd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19ce0 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
19cf0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
19d00 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
19d10 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
19d20 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
19d30 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
19d40 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65   of rows inserte
19d50 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a  d, modified or.*
19d60 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c  * deleted by all
19d70 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
19d80 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
19d90 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c  statements compl
19da0 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68  eted.** since th
19db0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
19dc0 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64  ction was opened
19dd0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73  , including thos
19de0 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a  e executed as.**
19df0 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72   part of trigger
19e00 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63   programs. ^Exec
19e10 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
19e20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
19e30 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f  ement.** does no
19e40 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c  t affect the val
19e50 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
19e60 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
19e70 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e  nges()..** .** ^
19e80 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20  Changes made as 
19e90 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e  part of [foreign
19ea0 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72   key actions] ar
19eb0 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  e included in th
19ec0 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20  e.** count, but 
19ed0 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61  those made as pa
19ee0 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f  rt of REPLACE co
19ef0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
19f00 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20  ion are.** not. 
19f10 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
19f20 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
19f30 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45  rcepted by INSTE
19f40 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a  AD OF triggers .
19f50 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
19f60 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61  ed..** .** See a
19f70 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
19f80 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
19f90 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
19fa0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
19fb0 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
19fc0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
19fd0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
19fe0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
19ff0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1a000 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1a010 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1a020 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1a030 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
1a040 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
1a050 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
1a060 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
1a070 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
1a080 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
1a090 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
1a0a0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50  PI int SQLITE_AP
1a0b0 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 6f  ICALL sqlite3_to
1a0c0 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
1a0d0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1a0e0 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
1a0f0 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
1a100 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44   Query.** METHOD
1a110 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1a120 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63  ^This function c
1a130 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
1a140 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
1a150 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
1a160 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
1a170 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
1a180 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
1a190 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
1a1a0 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
1a1b0 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
1a1c0 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
1a1d0 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
1a1e0 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
1a1f0 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
1a200 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
1a210 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
1a220 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
1a230 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  ely..**.** ^It i
1a240 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
1a250 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
1a260 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
1a270 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
1a280 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
1a290 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
1a2a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
1a2b0 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
1a2c0 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
1a2d0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
1a2e0 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
1a2f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a300 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
1a310 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
1a320 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
1a330 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
1a340 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  turns..**.** ^If
1a350 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
1a360 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
1a370 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
1a380 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
1a390 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1a3a0 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
1a3b0 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
1a3c0 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
1a3d0 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
1a3e0 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
1a3f0 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
1a400 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
1a410 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ^An SQL operatio
1a420 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
1a430 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
1a440 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
1a450 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  UPT]..** ^If the
1a460 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
1a470 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
1a480 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
1a490 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
1a4a0 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
1a4b0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
1a4c0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
1a4d0 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
1a4e0 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
1a4f0 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
1a500 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ically..**.** ^T
1a510 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1a520 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20  rupt(D) call is 
1a530 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20  in effect until 
1a540 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75  all currently ru
1a550 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
1a560 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61  tements on [data
1a570 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1a580 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41   D complete.  ^A
1a590 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
1a5a0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1a5b0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1a5c0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1a5d0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
1a5e0 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
1a5f0 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
1a600 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
1a610 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
1a620 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
1a630 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
1a640 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
1a650 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1a660 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20  call.  ^New SQL 
1a670 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1a680 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1a690 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67  fter the running
1a6a0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74   statement count
1a6b0 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
1a6c0 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65  e.** not effecte
1a6d0 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
1a6e0 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a  _interrupt()..**
1a6f0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69   ^A call to sqli
1a700 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
1a710 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65   that occurs whe
1a720 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72  n there are no r
1a730 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
1a740 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f  atements is a no
1a750 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65  -op and has no e
1a760 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
1a770 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1a780 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1a790 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
1a7a0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72  terrupt() call r
1a7b0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
1a7c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1a7d0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
1a7e0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
1a7f0 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
1a800 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
1a810 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
1a820 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
1a830 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1a840 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20   SQLITE_APICALL 
1a850 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1a860 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
1a870 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
1a880 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
1a890 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
1a8a0 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
1a8b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1a8c0 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63   useful during c
1a8d0 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
1a8e0 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
1a8f0 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
1a900 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
1a910 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20  seems to form a 
1a920 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
1a930 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
1a940 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
1a950 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
1a960 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
1a970 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
1a980 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
1a990 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1a9a0 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20  return 1 if the 
1a9b0 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
1a9c0 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
1a9d0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
1a9e0 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74  tement.  ^A stat
1a9f0 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
1aa00 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
1aa10 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
1aa20 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
1aa30 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
1aa40 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
1aa50 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
1aa60 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
1aa70 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f  ment.  ^Semicolo
1aa80 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
1aa90 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
1aaa0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
1aab0 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
1aac0 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
1aad0 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
1aae0 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
1aaf0 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
1ab00 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
1ab10 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
1ab20 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
1ab30 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
1ab40 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
1ab50 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ent terminator. 
1ab60 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20   ^Whitespace.** 
1ab70 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61  and comments tha
1ab80 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e  t follow the fin
1ab90 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65  al semicolon are
1aba0 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
1abb0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1abc0 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
1abd0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
1abe0 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a  omplete.  ^If a.
1abf0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
1ac00 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e  tion fails, then
1ac10 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73   SQLITE_NOMEM is
1ac20 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1ac30 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1ac40 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
1ac50 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
1ac60 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
1ac70 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
1ac80 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
1ac90 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66   SQL..**.** ^(If
1aca0 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20   SQLite has not 
1acb0 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  been initialized
1acc0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1acd0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72  initialize()] pr
1ace0 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b  ior .** to invok
1acf0 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ing sqlite3_comp
1ad00 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71  lete16() then sq
1ad10 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
1ad20 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
1ad30 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
1ad40 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  y sqlite3_comple
1ad50 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74  te16().  If that
1ad60 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
1ad70 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  fails,.** then t
1ad80 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1ad90 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d  from sqlite3_com
1ada0 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62  plete16() will b
1adb0 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65  e non-zero.** re
1adc0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1add0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69  her or not the i
1ade0 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70  nput SQL is comp
1adf0 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  lete.)^.**.** Th
1ae00 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
1ae10 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
1ae20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
1ae30 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1ae40 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
1ae50 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
1ae60 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1ae70 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
1ae80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1ae90 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
1aea0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
1aeb0 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  rder..*/.SQLITE_
1aec0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41  API int SQLITE_A
1aed0 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  PICALL sqlite3_c
1aee0 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
1aef0 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45  ar *sql);.SQLITE
1af00 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
1af10 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  APICALL sqlite3_
1af20 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
1af30 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
1af40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1af50 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
1af60 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
1af70 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
1af80 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73  * KEYWORDS: {bus
1af90 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
1afa0 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65  ck} {busy handle
1afb0 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
1afc0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1afd0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1afe0 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75  ndler(D,X,P) rou
1aff0 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
1b000 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a  back function X.
1b010 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  ** that might be
1b020 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
1b030 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
1b040 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
1b050 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1b060 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  s a database tab
1b070 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
1b080 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  th.** [database 
1b090 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68  connection] D wh
1b0a0 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  en another threa
1b0b0 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
1b0c0 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f  has the table lo
1b0d0 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cked..** The sql
1b0e0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1b0f0 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  r() interface is
1b100 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1b110 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nt.** [sqlite3_b
1b120 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61  usy_timeout()] a
1b130 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  nd [PRAGMA busy_
1b140 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20  timeout]..**.** 
1b150 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1b160 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
1b170 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
1b180 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
1b190 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
1b1a0 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
1b1b0 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
1b1c0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
1b1d0 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
1b1e0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
1b1f0 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
1b200 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
1b210 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1b220 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1b230 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
1b240 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
1b250 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
1b260 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
1b270 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
1b280 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
1b290 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
1b2a0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1b2b0 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
1b2c0 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
1b2d0 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
1b2e0 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
1b2f0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1b300 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
1b310 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20  oked previously 
1b320 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
1b330 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
1b340 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
1b350 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
1b360 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
1b370 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
1b380 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
1b390 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1b3a0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
1b3b0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ] is returned.**
1b3c0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1b3d0 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
1b3e0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1b3f0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
1b400 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
1b410 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  ** is made to ac
1b420 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1b430 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  e and the cycle 
1b440 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
1b450 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
1b460 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
1b470 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
1b480 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
1b490 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
1b4a0 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
1b4b0 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
1b4c0 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
1b4d0 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
1b4e0 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
1b4f0 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
1b500 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
1b510 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
1b520 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
1b530 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74  TE_BUSY].** to t
1b540 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1b550 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
1b560 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20  ng the .** busy 
1b570 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
1b580 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
1b590 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
1b5a0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1b5b0 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
1b5c0 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
1b5d0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
1b5e0 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
1b5f0 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
1b600 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1b610 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
1b620 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
1b630 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
1b640 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
1b650 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
1b660 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
1b670 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
1b680 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1b690 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
1b6a0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
1b6b0 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
1b6c0 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
1b6d0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1b6e0 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
1b6f0 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
1b700 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
1b710 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
1b720 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
1b730 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
1b740 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
1b750 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1b760 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
1b770 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
1b780 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
1b790 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
1b7a0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1b7b0 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
1b7c0 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
1b7d0 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
1b7e0 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
1b7f0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1b800 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
1b810 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
1b820 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1b830 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1b840 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
1b850 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
1b860 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1b870 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
1b880 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
1b890 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
1b8a0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1b8b0 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
1b8c0 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
1b8d0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1b8e0 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72  timeout()].** or
1b8f0 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41   evaluating [PRA
1b900 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1b910 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20  =N] will change 
1b920 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
1b930 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65  ler and thus cle
1b940 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  ar any previousl
1b950 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c  y set busy handl
1b960 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
1b970 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
1b980 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
1b990 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
1b9a0 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
1b9b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b9c0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1b9d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
1b9e0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a  In other words,.
1b9f0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1ba00 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ler is not reent
1ba10 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20  rant.  Any such 
1ba20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
1ba30 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
1ba40 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
1ba50 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
1ba60 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
1ba70 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1ba80 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
1ba90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1baa0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1bab0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1bac0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1bad0 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c  t SQLITE_APICALL
1bae0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1baf0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
1bb00 69 6e 74 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42  int(SQLITE_CALLB
1bb10 41 43 4b 20 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  ACK *)(void*,int
1bb20 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1bb30 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
1bb40 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a  A Busy Timeout.*
1bb50 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1bb60 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  3.**.** ^This ro
1bb70 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
1bb80 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1bb90 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
1bba0 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
1bbb0 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
1bbc0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
1bbd0 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
1bbe0 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
1bbf0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
1bc00 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
1bc10 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
1bc20 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1bc30 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1bc40 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
1bc50 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
1bc60 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1bc70 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1bc80 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
1bc90 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
1bca0 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
1bcb0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
1bcc0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
1bcd0 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  E_BUSY]..**.** ^
1bce0 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
1bcf0 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
1bd00 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
1bd10 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
1bd20 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
1bd30 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
1bd40 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
1bd50 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
1bd60 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
1bd70 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
1bd80 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1bd90 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e  onnection] at an
1bda0 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
1bdb0 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
1bdc0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
1bdd0 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
1bde0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1bdf0 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
1be00 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
1be10 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
1be20 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
1be30 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
1be40 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
1be50 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  :  [PRAGMA busy_
1be60 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53 51 4c 49  timeout].*/.SQLI
1be70 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
1be80 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65  E_APICALL sqlite
1be90 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
1bea0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
1beb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1bec0 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
1bed0 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
1bee0 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d  ing Queries.** M
1bef0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1bf00 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
1bf10 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
1bf20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
1bf30 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
1bf40 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1bf50 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
1bf60 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
1bf70 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
1bf80 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
1bf90 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
1bfa0 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
1bfb0 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
1bfc0 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
1bfd0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1bfe0 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
1bff0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1c000 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
1c010 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
1c020 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
1c030 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
1c040 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
1c050 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
1c060 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
1c070 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
1c080 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
1c090 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
1c0a0 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
1c0b0 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
1c0c0 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
1c0d0 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
1c0e0 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
1c0f0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1c100 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
1c110 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1c120 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
1c130 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1c140 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
1c150 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
1c160 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1c170 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
1c180 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
1c190 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
1c1a0 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
1c1b0 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
1c1c0 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
1c1d0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1c1e0 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
1c1f0 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
1c200 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
1c210 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
1c220 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
1c230 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
1c240 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
1c250 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
1c260 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
1c270 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
1c280 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
1c290 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1c2a0 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
1c2b0 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
1c2c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1c2d0 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
1c2e0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
1c2f0 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
1c300 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
1c310 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
1c320 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
1c330 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
1c340 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
1c350 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
1c360 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
1c370 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
1c380 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
1c390 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
1c3a0 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
1c3b0 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
1c3c0 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
1c3d0 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
1c3e0 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
1c3f0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
1c400 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1c410 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1c420 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
1c430 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
1c440 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
1c450 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
1c460 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
1c470 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
1c480 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
1c490 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
1c4a0 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
1c4b0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1c4c0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
1c4d0 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
1c4e0 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
1c4f0 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
1c500 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
1c510 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
1c520 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
1c530 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1c540 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
1c550 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
1c560 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
1c570 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
1c580 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
1c590 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1c5a0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1c5b0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
1c5c0 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
1c5d0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1c5e0 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
1c5f0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1c600 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
1c610 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1c620 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
1c630 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
1c640 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
1c650 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
1c660 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
1c670 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
1c680 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1c690 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
1c6a0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1c6b0 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
1c6c0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1c6d0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
1c6e0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1c6f0 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
1c700 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
1c710 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
1c720 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
1c730 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
1c740 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
1c750 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
1c760 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
1c770 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
1c780 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
1c790 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
1c7a0 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
1c7b0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
1c7c0 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
1c7d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
1c7e0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1c7f0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
1c800 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1c810 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
1c820 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
1c830 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
1c840 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1c850 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
1c860 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
1c870 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
1c880 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
1c890 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
1c8a0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
1c8b0 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
1c8c0 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
1c8d0 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
1c8e0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
1c8f0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
1c900 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
1c910 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
1c920 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
1c930 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1c940 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
1c950 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1c960 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
1c970 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
1c980 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1c990 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
1c9a0 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
1c9b0 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
1c9c0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
1c9d0 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
1c9e0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1c9f0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
1ca00 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
1ca10 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
1ca20 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
1ca30 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
1ca40 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
1ca50 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
1ca60 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
1ca70 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
1ca80 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
1ca90 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
1caa0 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
1cab0 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
1cac0 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
1cad0 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
1cae0 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
1caf0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
1cb00 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1cb10 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
1cb20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1cb30 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1cb40 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50  PI int SQLITE_AP
1cb50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67 65  ICALL sqlite3_ge
1cb60 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
1cb70 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1cb80 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
1cb90 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
1cba0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1cbb0 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
1cbc0 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
1cbd0 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
1cbe0 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
1cbf0 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
1cc00 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
1cc10 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1cc20 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
1cc30 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1cc40 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
1cc50 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1cc60 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
1cc70 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
1cc80 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
1cc90 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
1cca0 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
1ccb0 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  ere */.);.SQLITE
1ccc0 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
1ccd0 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33  _APICALL sqlite3
1cce0 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
1ccf0 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
1cd00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
1cd10 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
1cd20 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
1cd30 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1cd40 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61  tines are work-a
1cd50 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
1cd60 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
1cd70 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
1cd80 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
1cd90 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54   C library..** T
1cda0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e  hese routines un
1cdb0 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66  derstand most of
1cdc0 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20   the common K&R 
1cdd0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1cde0 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65  ns,.** plus some
1cdf0 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d   additional non-
1ce00 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73  standard formats
1ce10 2c 20 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77  , detailed below
1ce20 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73  ..** Note that s
1ce30 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20  ome of the more 
1ce40 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69  obscure formatti
1ce50 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20  ng options from 
1ce60 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72  recent.** C-libr
1ce70 61 72 79 20 73 74 61 6e 64 61 72 64 73 20 61 72  ary standards ar
1ce80 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  e omitted from t
1ce90 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  his implementati
1cea0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
1ceb0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
1cec0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
1ced0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
1cee0 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
1cef0 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
1cf00 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
1cf10 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
1cf20 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
1cf30 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1cf40 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
1cf50 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
1cf60 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
1cf70 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
1cf80 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
1cf90 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
1cfa0 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
1cfb0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
1cfc0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1cfd0 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
1cfe0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1cff0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
1d000 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  g..**.** ^(The s
1d010 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1d020 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
1d030 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
1d040 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
1d050 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1d060 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
1d070 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
1d080 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
1d090 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
1d0a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1d0b0 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
1d0c0 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
1d0d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
1d0e0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
1d0f0 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
1d100 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
1d110 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
1d120 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
1d130 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
1d140 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
1d150 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
1d160 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
1d170 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
1d180 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1d190 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
1d1a0 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
1d1b0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
1d1c0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1d1d0 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
1d1e0 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
1d1f0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
1d200 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
1d210 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
1d220 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
1d230 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
1d240 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1d250 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
1d260 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
1d270 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
1d280 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
1d290 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
1d2a0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
1d2b0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1d2c0 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
1d2d0 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
1d2e0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
1d2f0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
1d300 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
1d310 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
1d320 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1d330 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
1d340 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
1d350 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
1d360 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
1d370 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1d380 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
1d390 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
1d3a0 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
1d3b0 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
1d3c0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
1d3d0 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
1d3e0 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
1d3f0 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
1d400 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
1d410 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
1d420 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cters..**.** ^Th
1d430 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  e sqlite3_vsnpri
1d440 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1d450 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69   a varargs versi
1d460 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1d470 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20  printf()..**.** 
1d480 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1d490 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
1d4a0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
1d4b0 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
1d4c0 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
1d4d0 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
1d4e0 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
1d4f0 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
1d500 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
1d510 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1d520 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
1d530 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
1d540 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
1d550 25 51 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25  %Q", "%w" and "%
1d560 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  z" options..**.*
1d570 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f  * ^(The %q optio
1d580 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
1d590 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
1d5a0 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72  itutes a nul-ter
1d5b0 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1d5c0 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
1d5d0 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25  ent list.  But %
1d5e0 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65  q also doubles e
1d5f0 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63  very '\'' charac
1d600 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65  ter..** %q is de
1d610 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69  signed for use i
1d620 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c  nside a string l
1d630 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f  iteral.)^  By do
1d640 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
1d650 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
1d660 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
1d670 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
1d680 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
1d690 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
1d6a0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
1d6b0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75  or example, assu
1d6c0 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61  me the string va
1d6d0 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e  riable zText con
1d6e0 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
1d6f0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1d700 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1d710 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
1d720 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
1d730 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
1d740 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1d750 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
1d760 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
1d770 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
1d780 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1d790 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1d7a0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1d7b0 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1d7c0 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1d7d0 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
1d7e0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1d7f0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1d800 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1d810 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1d820 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1d830 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1d840 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
1d850 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
1d860 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
1d870 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
1d880 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
1d890 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
1d8a0 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is a
1d8b0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1d8c0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1d8d0 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1d8e0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1d8f0 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
1d900 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
1d910 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1d920 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
1d930 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
1d940 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
1d950 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
1d960 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
1d970 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
1d980 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
1d990 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1d9a0 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1d9b0 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1d9c0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1d9d0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1d9e0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1d9f0 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
1da00 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
1da10 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
1da20 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
1da30 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61  u should.** alwa
1da40 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
1da50 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
1da60 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
1da70 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1da80 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  l..**.** ^(The %
1da90 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
1daa0 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
1dab0 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
1dac0 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
1dad0 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
1dae0 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
1daf0 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
1db00 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
1db10 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
1db20 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
1db30 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
1db40 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
1db50 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
1db60 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
1db70 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c   quotes).)^  So,
1db80 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
1db90 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
1dba0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1dbb0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1dbc0 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1dbd0 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1dbe0 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1dbf0 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
1dc00 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1dc10 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1dc20 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1dc30 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1dc40 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1dc50 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
1dc60 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
1dc70 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
1dc80 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
1dc90 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
1dca0 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
1dcb0 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
1dcc0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1dcd0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77  .**.** ^(The "%w
1dce0 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1dcf0 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22  ion is like "%q"
1dd00 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
1dd10 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65  expects to.** be
1dd20 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69   contained withi
1dd30 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20  n double-quotes 
1dd40 69 6e 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c  instead of singl
1dd50 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74  e quotes, and it
1dd60 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 68 65 20  .** escapes the 
1dd70 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61  double-quote cha
1dd80 72 61 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f  racter instead o
1dd90 66 20 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f  f the single-quo
1dda0 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e  te.** character.
1ddb0 29 5e 20 20 54 68 65 20 22 25 77 22 20 66 6f 72  )^  The "%w" for
1ddc0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69  matting option i
1ddd0 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73  s intended for s
1dde0 61 66 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a  afely inserting.
1ddf0 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  ** table and col
1de00 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61  umn names into a
1de10 20 63 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c   constructed SQL
1de20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
1de30 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
1de40 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
1de50 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
1de60 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
1de70 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
1de80 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
1de90 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
1dea0 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
1deb0 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
1dec0 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
1ded0 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
1dee0 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
1def0 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1df00 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 71  *SQLITE_CDECL sq
1df10 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
1df20 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
1df30 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1df40 2a 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20  *SQLITE_APICALL 
1df50 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1df60 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
1df70 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41  _list);.SQLITE_A
1df80 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  PI char *SQLITE_
1df90 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 73 6e  CDECL sqlite3_sn
1dfa0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1dfb0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
1dfc0 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .);.SQLITE_API c
1dfd0 68 61 72 20 2a 53 51 4c 49 54 45 5f 41 50 49 43  har *SQLITE_APIC
1dfe0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  ALL sqlite3_vsnp
1dff0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1e000 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1e010 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
1e020 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1e030 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
1e040 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
1e050 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
1e060 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
1e070 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
1e080 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
1e090 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
1e0a0 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
1e0b0 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
1e0c0 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
1e0d0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
1e0e0 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
1e0f0 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
1e100 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
1e110 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
1e120 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
1e130 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1e140 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
1e150 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
1e160 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1e170 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1e180 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1e190 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
1e1a0 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
1e1b0 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
1e1c0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1e1d0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
1e1e0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
1e1f0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
1e200 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
1e210 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
1e220 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
1e230 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
1e240 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1e250 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
1e260 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
1e270 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
1e280 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
1e290 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
1e2a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1e2b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e2c0 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75  _malloc64(N) rou
1e2d0 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20  tine works just 
1e2e0 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  like.** sqlite3_
1e2f0 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74  malloc(N) except
1e300 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e   that N is an un
1e310 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e  signed 64-bit in
1e320 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1e330 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d   of a signed 32-
1e340 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  bit integer..**.
1e350 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
1e360 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
1e370 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
1e380 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
1e390 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1e3a0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1e3b0 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
1e3c0 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
1e3d0 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
1e3e0 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
1e3f0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
1e400 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
1e410 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
1e420 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
1e430 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
1e440 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
1e450 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
1e460 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
1e470 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
1e480 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
1e490 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
1e4a0 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
1e4b0 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
1e4c0 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
1e4d0 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
1e4e0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
1e4f0 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1e500 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
1e510 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
1e520 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
1e530 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
1e540 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
1e550 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
1e560 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
1e570 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1e580 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1e590 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
1e5a0 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
1e5b0 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
1e5c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e5d0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1e5e0 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  loc()..**.** ^Th
1e5f0 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
1e600 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  c(X,N) interface
1e610 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
1e620 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
1e630 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1e640 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73   X to be at leas
1e650 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49  t N bytes..** ^I
1e660 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65  f the X paramete
1e670 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1e680 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20  lloc(X,N).** is 
1e690 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1e6a0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
1e6b0 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
1e6c0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1e6d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a  te3_malloc(N)..*
1e6e0 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61  * ^If the N para
1e6f0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1e700 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73  _realloc(X,N) is
1e710 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
1e720 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
1e730 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
1e740 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
1e750 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1e760 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71  _free(X)..** ^sq
1e770 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1e780 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  N) returns a poi
1e790 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
1e7a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
1e7b0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
1e7c0 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
1e7d0 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
1e7e0 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61  nt memory is ava
1e7f0 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
1e800 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
1e810 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1e820 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
1e830 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
1e840 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1e850 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
1e860 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
1e870 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
1e880 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1e890 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1e8a0 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
1e8b0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
1e8c0 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  ed..** ^If sqlit
1e8d0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1e8e0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
1e8f0 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20   N is positive, 
1e900 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f  then the.** prio
1e910 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1e920 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
1e930 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
1e940 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74  alloc64(X,N) int
1e950 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68  erfaces works th
1e960 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c  e same as.** sql
1e970 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1e980 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
1e990 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69  is a 64-bit unsi
1e9a0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73  gned integer ins
1e9b0 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d  tead.** of a 32-
1e9c0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
1e9d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20  er..**.** ^If X 
1e9e0 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  is a memory allo
1e9f0 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c  cation previousl
1ea00 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
1ea10 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1ea20 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
1ea30 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33  loc64(), sqlite3
1ea40 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73  _realloc(), or s
1ea50 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1ea60 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  (), then.** sqli
1ea70 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
1ea80 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
1ea90 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c   that memory all
1eaa0 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73  ocation in bytes
1eab0 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20  ..** ^The value 
1eac0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1ead0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67  te3_msize(X) mig
1eae0 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ht be larger tha
1eaf0 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  n the number.** 
1eb00 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74  of bytes request
1eb10 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c  ed when X was al
1eb20 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20  located.  ^If X 
1eb30 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1eb40 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  r then.** sqlite
1eb50 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
1eb60 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70  ns zero.  If X p
1eb70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69  oints to somethi
1eb80 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a  ng that is not.*
1eb90 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  * the beginning 
1eba0 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
1ebb0 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70  tion, or if it p
1ebc0 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65  oints to a forme
1ebd0 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d  rly.** valid mem
1ebe0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1ebf0 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e  hat has now been
1ec00 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65   freed, then the
1ec10 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
1ec20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1ec30 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
1ec40 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66  d possibly harmf
1ec50 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ul..**.** ^The m
1ec60 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
1ec70 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1ec80 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
1ec90 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
1eca0 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e  3_malloc64(), an
1ecb0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
1ecc0 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  c64().** is alwa
1ecd0 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
1ece0 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
1ecf0 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
1ed00 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
1ed10 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
1ed20 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
1ed30 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
1ed40 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
1ed50 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
1ed60 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
1ed70 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
1ed80 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
1ed90 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
1eda0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
1edb0 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
1edc0 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
1edd0 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
1ede0 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
1edf0 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
1ee00 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
1ee10 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
1ee20 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
1ee30 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
1ee40 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
1ee50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
1ee60 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
1ee70 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
1ee80 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
1ee90 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
1eea0 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
1eeb0 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
1eec0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
1eed0 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
1eee0 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
1eef0 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
1ef00 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
1ef10 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
1ef20 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
1ef30 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
1ef40 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
1ef50 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
1ef60 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
1ef70 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
1ef80 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
1ef90 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
1efa0 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
1efb0 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
1efc0 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
1efd0 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
1efe0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
1eff0 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
1f000 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
1f010 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
1f020 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
1f030 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1f040 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1f050 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
1f060 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
1f070 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
1f080 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
1f090 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
1f0a0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1f0b0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
1f0c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1f0d0 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
1f0e0 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
1f0f0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
1f100 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
1f110 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
1f120 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
1f130 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
1f140 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
1f150 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
1f160 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1f170 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
1f180 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
1f190 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1f1a0 69 64 20 2a 53 51 4c 49 54 45 5f 41 50 49 43 41  id *SQLITE_APICA
1f1b0 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  LL sqlite3_mallo
1f1c0 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  c(int);.SQLITE_A
1f1d0 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  PI void *SQLITE_
1f1e0 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  APICALL sqlite3_
1f1f0 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33  malloc64(sqlite3
1f200 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45  _uint64);.SQLITE
1f210 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54  _API void *SQLIT
1f220 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65  E_APICALL sqlite
1f230 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
1f240 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
1f250 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 41  I void *SQLITE_A
1f260 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72  PICALL sqlite3_r
1f270 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20  ealloc64(void*, 
1f280 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
1f290 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1f2a0 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20   SQLITE_APICALL 
1f2b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
1f2c0 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  d*);.SQLITE_API 
1f2d0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 53  sqlite3_uint64 S
1f2e0 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71  QLITE_APICALL sq
1f2f0 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64  lite3_msize(void
1f300 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1f310 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1f320 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
1f330 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
1f340 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
1f350 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
1f360 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
1f370 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
1f380 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
1f390 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
1f3a0 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
1f3b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1f3c0 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
1f3d0 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
1f3e0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1f3f0 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
1f400 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
1f410 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1f420 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
1f430 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
1f440 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d  of bytes.** of m
1f450 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
1f460 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
1f470 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
1f480 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  eed)..** ^The [s
1f490 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1f4a0 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
1f4b0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
1f4c0 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20  aximum.** value 
1f4d0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  of [sqlite3_memo
1f4e0 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65  ry_used()] since
1f4f0 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1f500 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74  mark.** was last
1f510 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61   reset.  ^The va
1f520 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
1f530 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1f540 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1f550 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1f560 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63  highwater()] inc
1f570 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61  lude any overhea
1f580 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51  d.** added by SQ
1f590 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
1f5a0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
1f5b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1f5c0 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65  ,.** but not ove
1f5d0 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
1f5e0 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
1f5f0 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
1f600 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
1f610 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
1f620 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
1f630 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1f640 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1f650 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
1f660 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
1f670 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  f.** [sqlite3_me
1f680 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
1f690 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
1f6a0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
1f6b0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1f6c0 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20  highwater()] is 
1f6d0 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75  true.  ^The valu
1f6e0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
1f6f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1f700 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
1f710 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
1f720 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74   mark.** prior t
1f730 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
1f740 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
1f750 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f  e3_int64 SQLITE_
1f760 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  APICALL sqlite3_
1f770 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
1f780 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
1f790 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49  lite3_int64 SQLI
1f7a0 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74  TE_APICALL sqlit
1f7b0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1f7c0 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
1f7d0 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
1f7e0 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
1f7f0 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
1f800 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
1f810 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
1f820 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
1f830 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
1f840 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
1f850 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
1f860 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
1f870 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
1f880 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
1f890 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
1f8a0 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
1f8b0 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
1f8c0 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
1f8d0 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
1f8e0 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
1f8f0 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
1f900 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
1f910 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
1f920 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
1f930 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
1f940 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
1f950 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
1f960 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
1f970 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
1f980 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
1f990 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
1f9a0 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
1f9b0 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
1f9c0 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70  r P..** ^The P p
1f9d0 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20  arameter can be 
1f9e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1f9f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72  **.** ^If this r
1fa00 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62  outine has not b
1fa10 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63  een previously c
1fa20 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20  alled or if the 
1fa30 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c  previous.** call
1fa40 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e   had N less than
1fa50 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70   one or a NULL p
1fa60 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68  ointer for P, th
1fa70 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a  en the PRNG is.*
1fa80 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  * seeded using r
1fa90 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
1faa0 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ed from the xRan
1fab0 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
1fac0 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  f.** the default
1fad0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1fae0 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  bject..** ^If th
1faf0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
1fb00 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1fb10 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72  had an N of 1 or
1fb20 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e   more and a.** n
1fb30 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74  on-NULL P then t
1fb40 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
1fb50 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
1fb60 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
1fb70 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
1fb80 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
1fb90 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
1fba0 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
1fbb0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
1fbc0 6f 69 64 20 53 51 4c 49 54 45 5f 41 50 49 43 41  oid SQLITE_APICA
1fbd0 4c 4c 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  LL sqlite3_rando
1fbe0 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
1fbf0 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
1fc00 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
1fc10 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
1fc20 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  on Callbacks.** 
1fc30 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1fc40 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1fc50 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
1fc60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1fc70 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
1fc80 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1fc90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
1fca0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
1fcb0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
1fcc0 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
1fcd0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1fce0 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
1fcf0 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
1fd00 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
1fd10 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1fd20 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1fd30 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
1fd40 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
1fd50 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1fd60 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
1fd70 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1fd80 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
1fd90 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
1fda0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
1fdb0 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
1fdc0 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
1fdd0 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
1fde0 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
1fdf0 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
1fe00 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1fe10 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
1fe20 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
1fe30 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
1fe40 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
1fe50 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
1fe60 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
1fe70 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
1fe80 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
1fe90 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
1fea0 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
1feb0 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
1fec0 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
1fed0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
1fee0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
1fef0 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
1ff00 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
1ff10 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
1ff20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1ff30 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
1ff40 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
1ff50 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
1ff60 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
1ff70 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
1ff80 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1ff90 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
1ffa0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
1ffb0 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
1ffc0 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
1ffd0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1ffe0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1fff0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
20000 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
20010 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
20020 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
20030 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
20040 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
20050 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
20060 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
20070 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
20080 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
20090 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
200a0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
200b0 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
200c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
200d0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
200e0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
200f0 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
20100 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
20110 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
20120 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
20130 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
20140 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
20150 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
20160 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
20170 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
20180 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
20190 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
201a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
201b0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
201c0 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
201d0 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
201e0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
201f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
20200 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
20210 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
20220 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
20230 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
20240 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
20250 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
20260 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
20270 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
20280 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
20290 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
202a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
202b0 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
202c0 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
202d0 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
202e0 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
202f0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
20300 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
20310 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
20320 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
20330 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
20340 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
20350 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
20360 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20370 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
20380 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
20390 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
203a0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
203b0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
203c0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
203d0 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
203e0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
203f0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
20400 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
20410 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
20420 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
20430 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
20440 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
20450 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
20460 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
20470 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
20480 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
20490 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
204a0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
204b0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
204c0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
204d0 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
204e0 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
204f0 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
20500 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
20510 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
20520 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
20530 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
20540 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
20550 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
20560 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
20570 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
20580 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
20590 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
205a0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
205b0 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
205c0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
205d0 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
205e0 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
205f0 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
20600 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
20610 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
20620 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
20630 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
20640 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
20650 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
20660 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
20670 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
20680 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
20690 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
206a0 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
206b0 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
206c0 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
206d0 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
206e0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
206f0 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
20700 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
20710 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
20720 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
20730 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
20740 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
20750 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
20760 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
20770 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
20780 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
20790 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
207a0 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
207b0 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
207c0 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
207d0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
207e0 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
207f0 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
20800 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
20810 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
20820 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
20830 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
20840 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
20850 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
20860 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
20870 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
20880 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
20890 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
208a0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
208b0 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
208c0 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
208d0 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
208e0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
208f0 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
20900 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
20910 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20920 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
20930 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
20940 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
20950 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
20960 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
20970 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
20980 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20990 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
209a0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
209b0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
209c0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
209d0 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
209e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
209f0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
20a00 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
20a10 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
20a20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
20a30 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
20a40 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
20a50 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
20a60 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
20a70 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
20a80 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
20a90 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
20aa0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
20ab0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
20ac0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
20ad0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
20ae0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
20af0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
20b00 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
20b10 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
20b20 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
20b30 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
20b40 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
20b50 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
20b60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20b70 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
20b80 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
20b90 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
20ba0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
20bb0 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
20bc0 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
20bd0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
20be0 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
20bf0 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
20c00 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
20c10 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
20c20 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20c30 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
20c40 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
20c50 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
20c60 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
20c70 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
20c80 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
20c90 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
20ca0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
20cb0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
20cc0 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
20cd0 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
20ce0 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
20cf0 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
20d00 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
20d10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
20d20 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
20d30 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
20d40 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
20d50 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
20d60 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43   int SQLITE_APIC
20d70 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  ALL sqlite3_set_
20d80 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
20d90 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 53  lite3*,.  int (S
20da0 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a  QLITE_CALLBACK *
20db0 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
20dc0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
20dd0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
20de0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
20df0 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
20e00 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
20e10 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
20e20 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
20e30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
20e40 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
20e50 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
20e60 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
20e70 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
20e80 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
20e90 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
20ea0 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
20eb0 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
20ec0 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
20ed0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
20ee0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
20ef0 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
20f00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
20f10 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
20f20 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
20f30 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
20f40 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
20f50 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
20f60 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
20f70 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
20f80 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74  d as a [conflict
20f90 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65   resolution mode
20fa0 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72  ].** returned fr
20fb0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
20fc0 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
20fd0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
20fe0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20ff0 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
21000 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
21010 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
21020 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
21030 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
21040 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
21050 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
21060 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
21070 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
21080 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
21090 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
210a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
210b0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
210c0 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
210d0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
210e0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
210f0 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
21100 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
21110 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
21120 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
21130 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
21140 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
21150 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
21160 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
21170 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
21180 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
21190 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
211a0 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
211b0 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
211c0 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
211d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
211e0 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
211f0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
21200 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
21210 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
21220 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
21230 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
21240 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
21250 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
21260 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
21270 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
21280 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
21290 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
212a0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
212b0 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
212c0 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
212d0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
212e0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
212f0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
21300 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
21310 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
21320 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
21330 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
21340 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
21350 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
21360 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
21370 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
21380 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21390 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
213a0 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
213b0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
213c0 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
213d0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
213e0 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
213f0 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
21400 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
21410 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
21420 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
21430 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
21440 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21450 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21460 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
21470 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
21480 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
21490 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
214a0 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
214b0 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
214c0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
214d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
214e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
214f0 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
21500 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
21510 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
21520 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21530 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
21540 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
21550 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
21560 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
21570 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21580 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21590 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
215a0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
215b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
215c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
215d0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
215e0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
215f0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
21600 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
21610 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21620 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
21630 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
21640 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
21650 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21660 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21670 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
21680 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
21690 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
216a0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
216b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
216c0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
216d0 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
216e0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
216f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21700 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21710 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
21720 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
21730 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21740 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21750 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21760 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
21770 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
21780 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
21790 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
217a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
217b0 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
217c0 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
217d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
217e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
217f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21800 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
21810 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
21820 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
21830 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
21840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21850 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
21860 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
21870 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
21880 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
218a0 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
218b0 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
218c0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
218d0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
218e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
218f0 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
21900 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
21910 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
21920 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21930 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
21940 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
21950 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
21960 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
21970 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21980 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21990 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
219a0 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
219b0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
219c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
219d0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
219e0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
219f0 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
21a00 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
21a10 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21a20 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
21a30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
21a40 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
21a50 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
21a60 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
21a70 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
21a80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
21a90 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21aa0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
21ab0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
21ac0 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
21ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
21ae0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
21af0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21b00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21b10 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
21b20 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
21b30 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
21b40 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21b50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21b60 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
21b70 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
21b80 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21b90 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
21ba0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21bb0 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
21bc0 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
21bd0 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
21be0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21bf0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21c00 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
21c10 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
21c20 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
21c30 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21c50 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
21c60 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
21c70 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
21c80 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21c90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21ca0 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
21cb0 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
21cc0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
21cd0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21ce0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21cf0 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
21d00 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
21d10 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
21d20 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21d30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21d40 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
21d50 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
21d60 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
21d70 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
21d80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21d90 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
21da0 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
21db0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
21dc0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
21dd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
21de0 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
21df0 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
21e00 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
21e10 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
21e20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
21e30 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
21e40 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
21e50 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
21e60 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
21e70 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
21e80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21e90 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
21ea0 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69  er used */.#defi
21eb0 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53  ne SQLITE_RECURS
21ec0 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33  IVE            3
21ed0 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  3   /* NULL     
21ee0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
21ef0 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a         */../*.**
21f00 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
21f10 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
21f20 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45   Functions.** ME
21f30 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
21f40 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
21f50 65 73 20 61 72 65 20 64 65 70 72 65 63 61 74 65  es are deprecate
21f60 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69  d. Use the [sqli
21f70 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20  te3_trace_v2()] 
21f80 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73  interface.** ins
21f90 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74  tead of the rout
21fa0 69 6e 65 73 20 64 65 73 63 72 69 62 65 64 20 68  ines described h
21fb0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ere..**.** These
21fc0 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
21fd0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
21fe0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
21ff0 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
22000 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
22010 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
22020 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
22030 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
22040 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
22050 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
22060 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
22070 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
22080 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
22090 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
220a0 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
220b0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
220c0 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  ep()]..** ^The s
220d0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
220e0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
220f0 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20  ed with a UTF-8 
22100 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
22110 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
22120 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74  t text as the st
22130 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
22140 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a  gins executing..
22150 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20  ** ^(Additional 
22160 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
22170 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20  callbacks might 
22180 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
22190 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
221a0 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
221b0 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
221c0 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
221d0 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
221e0 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
221f0 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
22200 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a   trigger.)^.**.*
22210 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52  * The [SQLITE_TR
22220 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20  ACE_SIZE_LIMIT] 
22230 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
22240 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
22250 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20  to limit.** the 
22260 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64  length of [bound
22270 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61   parameter] expa
22280 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74  nsion in the out
22290 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74  put of sqlite3_t
222a0 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  race()..**.** ^T
222b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
222c0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
222d0 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
222e0 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
222f0 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
22300 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
22310 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
22320 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
22330 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
22340 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
22350 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
22360 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
22370 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
22380 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
22390 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20  nt took to run. 
223a0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
223b0 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69  llback.** time i
223c0 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61  s in units of na
223d0 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76  noseconds, howev
223e0 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  er the current i
223f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
22400 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65   is only capable
22410 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20   of millisecond 
22420 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68  resolution so th
22430 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e  e six least sign
22440 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74  ificant.** digit
22450 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72  s in the time ar
22460 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20  e meaningless.  
22470 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
22480 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67  of SQLite.** mig
22490 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74  ht provide great
224a0 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e  er resolution on
224b0 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61   the profiler ca
224c0 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20  llback.  The.** 
224d0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
224e0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f  ) function is co
224f0 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
22500 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20  ental and is.** 
22510 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
22520 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  e in future vers
22530 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
22540 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  */.SQLITE_API SQ
22550 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
22560 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 41 50 49  void *SQLITE_API
22570 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 61  CALL sqlite3_tra
22580 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  ce(sqlite3*,.   
22590 76 6f 69 64 28 53 51 4c 49 54 45 5f 43 41 4c 4c  void(SQLITE_CALL
225a0 42 41 43 4b 20 2a 78 54 72 61 63 65 29 28 76 6f  BACK *xTrace)(vo
225b0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
225c0 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
225d0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
225e0 45 43 41 54 45 44 20 76 6f 69 64 20 2a 53 51 4c  ECATED void *SQL
225f0 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69  ITE_APICALL sqli
22600 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
22610 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 53 51  te3*,.   void(SQ
22620 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78  LITE_CALLBACK *x
22630 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
22640 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
22650 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
22660 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
22670 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45  REF: SQL Trace E
22680 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  vent Codes.** KE
22690 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
226a0 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  RACE.**.** These
226b0 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74   constants ident
226c0 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65  ify classes of e
226d0 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62  vents that can b
226e0 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75  e monitored.** u
226f0 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  sing the [sqlite
22700 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72  3_trace_v2()] tr
22710 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68  acing logic.  Th
22720 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
22730 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
22740 74 72 61 63 65 5f 76 32 28 29 5d 20 69 73 20 61  trace_v2()] is a
22750 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74  n OR-ed combinat
22760 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ion of one or mo
22770 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  re of.** the fol
22780 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  lowing constants
22790 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  .  ^The first ar
227a0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72  gument to the tr
227b0 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ace callback.** 
227c0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  is one of the fo
227d0 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74  llowing constant
227e0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61  s..**.** New tra
227f0 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d  cing constants m
22800 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
22810 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
22820 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63  **.** ^A trace c
22830 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72  allback has four
22840 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c   arguments: xCal
22850 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a  lback(T,C,P,X)..
22860 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65  ** ^The T argume
22870 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  nt is one of the
22880 20 69 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f   integer type co
22890 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54  des above..** ^T
228a0 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73  he C argument is
228b0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63   a copy of the c
228c0 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70  ontext pointer p
228d0 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
228e0 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  ** fourth argume
228f0 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  nt to [sqlite3_t
22900 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54  race_v2()]..** T
22910 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d  he P and X argum
22920 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72  ents are pointer
22930 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73  s whose meanings
22940 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a   depend on T..**
22950 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
22960 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d  LITE_TRACE_STMT]
22970 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
22980 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20  CE_STMT</dt>.** 
22990 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
229a0 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61  RACE_STMT callba
229b0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
229c0 65 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74  en a prepared st
229d0 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74  atement.** first
229e0 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20   begins running 
229f0 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20  and possibly at 
22a00 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75 72 69  other times duri
22a10 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74  ng the.** execut
22a20 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61  ion of the prepa
22a30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73  red statement, s
22a40 75 63 68 20 61 73 20 61 74 20 74 68 65 20 73 74  uch as at the st
22a50 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74  art of each.** t
22a60 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61  rigger subprogra
22a70 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  m. ^The P argume
22a80 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
22a90 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  to the.** [prepa
22aa0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
22ab0 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20  ^The X argument 
22ac0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
22ad0 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a  a string which.*
22ae0 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e  * is the unexpan
22af0 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20  ded SQL text of 
22b00 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
22b10 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c  tement or an SQL
22b20 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61   comment .** tha
22b30 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20  t indicates the 
22b40 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20  invocation of a 
22b50 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63  trigger.  ^The c
22b60 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70  allback can comp
22b70 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ute.** the same 
22b80 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20  text that would 
22b90 68 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e  have been return
22ba0 65 64 20 62 79 20 74 68 65 20 6c 65 67 61 63 79  ed by the legacy
22bb0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
22bc0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
22bd0 62 79 20 75 73 69 6e 67 20 74 68 65 20 58 20 61  by using the X a
22be0 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62  rgument when X b
22bf0 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20  egins with "--" 
22c00 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20  and invoking.** 
22c10 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65  [sqlite3_expande
22c20 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77  d_sql(P)] otherw
22c30 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ise..**.** [[SQL
22c40 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
22c50 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  E]] <dt>SQLITE_T
22c60 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74  RACE_PROFILE</dt
22c70 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
22c80 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
22c90 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69  E callback provi
22ca0 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c  des approximatel
22cb0 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e  y the same.** in
22cc0 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20  formation as is 
22cd0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
22ce0 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
22cf0 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ()] callback..**
22d00 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
22d10 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
22d20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
22d30 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68  tatement] and th
22d40 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20  e.** X argument 
22d50 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62  points to a 64-b
22d60 69 74 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  it integer which
22d70 20 69 73 20 74 68 65 20 65 73 74 69 6d 61 74 65   is the estimate
22d80 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  d of.** the numb
22d90 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  er of nanosecond
22da0 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72   that the prepar
22db0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  ed statement too
22dc0 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68  k to run..** ^Th
22dd0 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  e SQLITE_TRACE_P
22de0 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20  ROFILE callback 
22df0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
22e00 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
22e10 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  nishes..**.** [[
22e20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
22e30 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
22e40 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20  ACE_ROW</dt>.** 
22e50 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
22e60 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63  RACE_ROW callbac
22e70 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
22e80 6e 65 76 65 72 20 61 20 70 72 65 70 61 72 65 64  never a prepared
22e90 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65  .** statement ge
22ea0 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65  nerates a single
22eb0 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20   row of result. 
22ec0 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75   .** ^The P argu
22ed0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
22ee0 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  r to the [prepar
22ef0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
22f00 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d  d the.** X argum
22f10 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a  ent is unused..*
22f20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
22f30 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e  ACE_CLOSE]] <dt>
22f40 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
22f50 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  SE</dt>.** <dd>^
22f60 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
22f70 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69  CLOSE callback i
22f80 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
22f90 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
22fa0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a  nection closes..
22fb0 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  ** ^The P argume
22fc0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
22fd0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
22fe0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a   connection] obj
22ff0 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58  ect.** and the X
23000 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75   argument is unu
23010 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  sed..** </dl>.*/
23020 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23030 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20  TRACE_STMT      
23040 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51   0x01.#define SQ
23050 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
23060 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65 66 69  LE    0x02.#defi
23070 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
23080 52 4f 57 20 20 20 20 20 20 20 20 30 78 30 34 0a  ROW        0x04.
23090 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
230a0 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20  RACE_CLOSE      
230b0 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0x08../*.** CAPI
230c0 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20  3REF: SQL Trace 
230d0 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Hook.** METHOD: 
230e0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
230f0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
23100 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74  _v2(D,M,X,P) int
23110 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
23120 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63   a trace callbac
23130 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
23140 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73  against [databas
23150 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
23160 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20   using property 
23170 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f  mask M.** and co
23180 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e  ntext pointer P.
23190 20 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c    ^If the X call
231a0 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20  back is.** NULL 
231b0 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b  or if the M mask
231c0 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74   is zero, then t
231d0 72 61 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c  racing is disabl
231e0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72  ed.  The.** M ar
231f0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
23200 20 74 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d   the bitwise OR-
23210 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f  ed combination o
23220 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  f.** zero or mor
23230 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d  e [SQLITE_TRACE]
23240 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a   constants..**.*
23250 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  * ^Each call to 
23260 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74  either sqlite3_t
23270 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65  race() or sqlite
23280 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65  3_trace_v2() ove
23290 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63  rrides .** (canc
232a0 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63  els) any prior c
232b0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
232c0 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74  trace() or sqlit
232d0 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a  e3_trace_v2()..*
232e0 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c  *.** ^The X call
232f0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
23300 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20  whenever any of 
23310 74 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74  the events ident
23320 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73  ified by .** mas
23330 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65  k M occur.  ^The
23340 20 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20   integer return 
23350 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63  value from the c
23360 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65  allback is curre
23370 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c  ntly.** ignored,
23380 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79   though this may
23390 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
233a0 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c  e releases.  Cal
233b0 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lback.** impleme
233c0 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
233d0 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65  return zero to e
233e0 6e 73 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d  nsure future com
233f0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
23400 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62  * ^A trace callb
23410 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
23420 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e  ith four argumen
23430 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43  ts: callback(T,C
23440 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54  ,P,X)..** ^The T
23450 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
23460 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
23470 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61  TRACE].** consta
23480 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20  nts to indicate 
23490 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  why the callback
234a0 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a   was invoked..**
234b0 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74   ^The C argument
234c0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
234d0 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65  e context pointe
234e0 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20  r..** The P and 
234f0 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20  X arguments are 
23500 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d  pointers whose m
23510 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f  eanings depend o
23520 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  n T..**.** The s
23530 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
23540 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
23550 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61  ntended to repla
23560 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ce the legacy.**
23570 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
23580 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e  ite3_trace()] an
23590 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d [sqlite3_profi
235a0 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77  le()], both of w
235b0 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72  hich.** are depr
235c0 65 63 61 74 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  ecated..*/.SQLIT
235d0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
235e0 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33  _APICALL sqlite3
235f0 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c  _trace_v2(.  sql
23600 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65  ite3*,.  unsigne
23610 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 53  d uMask,.  int(S
23620 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a  QLITE_CALLBACK *
23630 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67  xCallback)(unsig
23640 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c  ned,void*,void*,
23650 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  void*),.  void *
23660 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pCtx.);../*.** C
23670 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
23680 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
23690 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
236a0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
236b0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
236c0 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
236d0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
236e0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
236f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
23700 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
23710 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
23720 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
23730 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
23740 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
23750 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
23760 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
23770 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
23780 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23790 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
237a0 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
237b0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
237c0 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
237d0 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
237e0 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
237f0 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
23800 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
23810 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
23820 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
23830 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
23840 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
23850 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
23860 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d   approximate num
23870 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
23880 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
23890 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
238a0 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
238b0 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
238c0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
238d0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
238e0 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  .  ^If N is less
238f0 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74   than one then t
23900 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68  he progress.** h
23910 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c  andler is disabl
23920 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  ed..**.** ^Only 
23930 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
23940 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
23950 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
23960 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
23970 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23980 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
23990 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
239a0 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
239b0 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
239c0 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
239d0 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
239e0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
239f0 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
23a00 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
23a10 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
23a20 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
23a30 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
23a40 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
23a50 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
23a60 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
23a70 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
23a80 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
23a90 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
23aa0 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
23ab0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
23ac0 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
23ad0 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
23ae0 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
23af0 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
23b00 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
23b10 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
23b20 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
23b30 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
23b40 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
23b50 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
23b60 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
23b70 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
23b80 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
23b90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
23ba0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
23bb0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
23bc0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
23bd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
23be0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
23bf0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
23c00 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
23c10 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  **.*/.SQLITE_API
23c20 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 41 50 49   void SQLITE_API
23c30 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 6f  CALL sqlite3_pro
23c40 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
23c50 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
23c60 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b  (SQLITE_CALLBACK
23c70 20 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64   *)(void*), void
23c80 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
23c90 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
23ca0 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
23cb0 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52  ection.** CONSTR
23cc0 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a  UCTOR: sqlite3.*
23cd0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
23ce0 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c  ines open an SQL
23cf0 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ite database fil
23d00 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62  e as specified b
23d10 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61  y the .** filena
23d20 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68  me argument. ^Th
23d30 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
23d40 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
23d50 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a  ed as UTF-8 for.
23d60 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
23d70 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
23d80 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55  en_v2() and as U
23d90 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
23da0 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65  ive byte.** orde
23db0 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  r for sqlite3_op
23dc0 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74  en16(). ^(A [dat
23dd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23de0 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61  ] handle is usua
23df0 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lly.** returned 
23e00 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69  in *ppDb, even i
23e10 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
23e20 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63  s.  The only exc
23e30 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a  eption is that.*
23e40 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75  * if SQLite is u
23e50 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
23e60 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
23e70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
23e80 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c  bject,.** a NULL
23e90 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e   will be written
23ea0 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74   into *ppDb inst
23eb0 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72  ead of a pointer
23ec0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
23ed0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e  ].** object.)^ ^
23ee0 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  (If the database
23ef0 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f   is opened (and/
23f00 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63  or created) succ
23f10 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a  essfully, then.*
23f20 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  * [SQLITE_OK] is
23f30 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
23f40 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
23f50 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
23f60 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71  d.)^ ^The.** [sq
23f70 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
23f80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
23f90 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  sg16()] routines
23fa0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
23fb0 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67  obtain.** an Eng
23fc0 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65  lish language de
23fd0 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
23fe0 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67   error following
23ff0 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e   a failure of an
24000 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  y.** of the sqli
24010 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69  te3_open() routi
24020 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nes..**.** ^The 
24030 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
24040 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66   will be UTF-8 f
24050 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72 65  or databases cre
24060 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71  ated using.** sq
24070 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
24080 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24090 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74  ).  ^The default
240a0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61   encoding for da
240b0 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74  tabases.** creat
240c0 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
240d0 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62  _open16() will b
240e0 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  e UTF-16 in the 
240f0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
24100 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  r..**.** Whether
24110 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
24120 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
24130 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
24140 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
24150 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
24160 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24170 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
24180 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
24190 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
241a0 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
241b0 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
241c0 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
241d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
241e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
241f0 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
24200 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
24210 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
24220 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
24230 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
24240 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
24250 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
24260 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
24270 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
24280 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
24290 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
242a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
242b0 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
242c0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
242d0 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
242e0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
242f0 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
24300 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
24310 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
24320 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
24330 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
24340 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53  REDCACHE],.** [S
24350 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
24360 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72  TECACHE], and/or
24370 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
24380 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  I] flags:)^.**.*
24390 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
243a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
243b0 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
243c0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
243d0 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
243e0 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
243f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
24400 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
24410 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
24420 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
24430 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
24440 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
24450 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
24460 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
24470 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
24480 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
24490 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
244a0 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
244b0 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
244c0 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
244d0 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
244e0 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
244f0 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
24500 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
24510 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
24520 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
24530 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
24540 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
24550 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
24560 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
24570 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
24580 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
24590 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
245a0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
245b0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
245c0 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
245d0 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
245e0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
245f0 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
24600 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
24610 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
24620 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
24630 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
24640 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
24650 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
24660 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
24670 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
24680 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
24690 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
246a0 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
246b0 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  e optionally com
246c0 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72  bined with other
246d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
246e0 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49  _READONLY | SQLI
246f0 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a  TE_OPEN_* bits].
24700 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
24710 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
24720 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
24730 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
24740 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
24750 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
24760 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24770 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
24780 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
24790 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
247a0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
247b0 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
247c0 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
247d0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
247e0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
247f0 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
24800 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
24810 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
24820 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
24830 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24840 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
24850 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
24860 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
24870 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
24880 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
24890 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
248a0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
248b0 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
248c0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
248d0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
248e0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
248f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24900 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
24910 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
24920 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
24930 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
24940 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
24950 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
24960 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
24970 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
24980 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
24990 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
249a0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
249b0 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
249c0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
249d0 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
249e0 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
249f0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
24a00 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
24a10 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
24a20 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
24a30 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
24a40 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
24a50 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
24a60 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
24a70 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
24a80 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
24a90 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
24aa0 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
24ab0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
24ac0 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
24ad0 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
24ae0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
24af0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
24b00 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
24b10 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
24b20 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
24b30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
24b40 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
24b50 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
24b60 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
24b70 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
24b80 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
24b90 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
24ba0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d  tion.  ^This in-
24bb0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
24bc0 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
24bd0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
24be0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
24bf0 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
24c00 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
24c10 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
24c20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
24c30 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
24c40 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
24c50 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
24c60 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
24c70 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
24c80 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
24c90 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
24ca0 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
24cb0 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
24cc0 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
24cd0 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
24ce0 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
24cf0 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
24d00 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
24d10 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  biguity..**.** ^
24d20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
24d30 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
24d40 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
24d50 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
24d60 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
24d70 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
24d80 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74  d.  ^This privat
24d90 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
24da0 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
24db0 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
24dc0 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
24dd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
24de0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
24df0 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  [[URI filenames 
24e00 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  in sqlite3_open(
24e10 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65  )]] <h3>URI File
24e20 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  names</h3>.**.**
24e30 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61   ^If [URI filena
24e40 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69  me] interpretati
24e50 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61  on is enabled, a
24e60 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  nd the filename 
24e70 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69  argument.** begi
24e80 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  ns with "file:",
24e90 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61   then the filena
24ea0 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  me is interprete
24eb0 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49  d as a URI. ^URI
24ec0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  .** filename int
24ed0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
24ee0 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53  nabled if the [S
24ef0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
24f00 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69  flag is.** set i
24f10 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
24f20 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
24f30 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
24f40 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
24f50 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
24f60 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
24f70 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
24f80 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
24f90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
24fa0 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
24fb0 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
24fc0 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
24fd0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
24fe0 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
24ff0 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20  sion 3.7.7, URI 
25000 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
25010 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65  etation is turne
25020 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61  d off.** by defa
25030 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20  ult, but future 
25040 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
25050 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20  te might enable 
25060 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  URI filename.** 
25070 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62  interpretation b
25080 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20  y default.  See 
25090 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d  "[URI filenames]
250a0 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  " for additional
250b0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
250c0 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  .**.** URI filen
250d0 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20  ames are parsed 
250e0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43  according to RFC
250f0 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55   3986. ^If the U
25100 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a  RI contains an.*
25110 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65  * authority, the
25120 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74  n it must be eit
25130 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72  her an empty str
25140 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e  ing or the strin
25150 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74  g .** "localhost
25160 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  ". ^If the autho
25170 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65  rity is not an e
25180 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22  mpty string or "
25190 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a  localhost", an .
251a0 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  ** error is retu
251b0 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c  rned to the call
251c0 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e  er. ^The fragmen
251d0 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
251e0 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65   URI, if .** pre
251f0 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64  sent, is ignored
25200 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
25210 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f  uses the path co
25220 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55  mponent of the U
25230 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f  RI as the name o
25240 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a  f the disk file.
25250 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e  ** which contain
25260 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
25270 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67  ^If the path beg
25280 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63  ins with a '/' c
25290 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68  haracter, .** th
252a0 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  en it is interpr
252b0 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c  eted as an absol
252c0 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68  ute path. ^If th
252d0 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20  e path does not 
252e0 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61  begin .** with a
252f0 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68   '/' (meaning th
25300 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  at the authority
25310 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74   section is omit
25320 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49  ted from the URI
25330 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61  ).** then the pa
25340 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  th is interprete
25350 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20  d as a relative 
25360 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77  path. .** ^(On w
25370 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73  indows, the firs
25380 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
25390 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20  n absolute path 
253a0 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73  .** is a drive s
253b0 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e  pecification (e.
253c0 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a  g. "C:").)^.**.*
253d0 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65  * [[core URI que
253e0 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a  ry parameters]].
253f0 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d  ** The query com
25400 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
25410 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61  may contain para
25420 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
25430 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65  interpreted.** e
25440 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20  ither by SQLite 
25450 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20  itself, or by a 
25460 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46  [VFS | custom VF
25470 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
25480 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64  ]..** SQLite and
25490 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56   its built-in [V
254a0 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20  FSes] interpret 
254b0 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  the.** following
254c0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
254d0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
254e0 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f     <li> <b>vfs</
254f0 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70  b>: ^The "vfs" p
25500 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
25510 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20  used to specify 
25520 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20  the name of.**  
25530 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20     a VFS object 
25540 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68  that provides th
25550 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
25560 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
25570 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20  t should.**     
25580 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73  be used to acces
25590 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
255a0 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66  ile on disk. ^If
255b0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
255c0 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e  set to.**     an
255d0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68   empty string th
255e0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62  e default VFS ob
255f0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53  ject is used. ^S
25600 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
25610 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20  nown.**     VFS 
25620 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66  is an error. ^If
25630 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
25640 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
25650 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73  he vfs option is
25660 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c  .**     present,
25670 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70   then the VFS sp
25680 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
25690 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63  ption takes prec
256a0 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20  edence over.**  
256b0 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73     the value pas
256c0 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
256d0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
256e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
256f0 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
25700 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68  b>mode</b>: ^(Th
25710 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
25720 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
25730 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22  ither "ro", "rw"
25740 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20  ,.**     "rwc", 
25750 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74  or "memory". Att
25760 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69  empting to set i
25770 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76  t to any other v
25780 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61  alue is.**     a
25790 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20  n error)^. .**  
257a0 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73     ^If "ro" is s
257b0 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74  pecified, then t
257c0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
257d0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f  pened for read-o
257e0 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  nly .**     acce
257f0 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74  ss, just as if t
25800 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
25810 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68  READONLY] flag h
25820 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74  ad been set in t
25830 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64  he .**     third
25840 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
25850 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
25860 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
25870 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a  ion is set to .*
25880 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e  *     "rw", then
25890 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
258a0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
258b0 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20  -write (but not 
258c0 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20  create) .**     
258d0 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51  access, as if SQ
258e0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
258f0 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c  ITE (but not SQL
25900 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29  ITE_OPEN_CREATE)
25910 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65   had .**     bee
25920 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72  n set. ^Value "r
25930 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  wc" is equivalen
25940 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74  t to setting bot
25950 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  h .**     SQLITE
25960 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
25970 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  and SQLITE_OPEN_
25980 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65  CREATE.  ^If the
25990 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a   mode option is.
259a0 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d  **     set to "m
259b0 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75  emory" then a pu
259c0 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  re [in-memory da
259d0 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76  tabase] that nev
259e0 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20  er reads.**     
259f0 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64  or writes from d
25a00 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74  isk is used. ^It
25a10 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20   is an error to 
25a20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20  specify a value 
25a30 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d  for.**     the m
25a40 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  ode parameter th
25a50 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72  at is less restr
25a60 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74  ictive than that
25a70 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
25a80 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70       the flags p
25a90 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69  assed in the thi
25aa0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
25ab0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25ac0 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
25ad0 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54  <b>cache</b>: ^T
25ae0 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
25af0 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
25b00 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22   either "shared"
25b10 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76   or.**     "priv
25b20 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69  ate". ^Setting i
25b30 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73  t to "shared" is
25b40 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
25b50 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  etting the.**   
25b60 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48    SQLITE_OPEN_SH
25b70 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e  AREDCACHE bit in
25b80 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
25b90 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a  ent passed to.**
25ba0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65       sqlite3_ope
25bb0 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67  n_v2(). ^Setting
25bc0 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d   the cache param
25bd0 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65  eter to "private
25be0 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75  " is .**     equ
25bf0 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
25c00 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  ng the SQLITE_OP
25c10 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
25c20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20  bit..**     ^If 
25c30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25c40 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
25c50 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65  e "cache" parame
25c60 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69  ter is present i
25c70 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66  n.**     a URI f
25c80 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c  ilename, its val
25c90 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79  ue overrides any
25ca0 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73   behavior reques
25cb0 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a  ted by setting.*
25cc0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
25cd0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f  N_PRIVATECACHE o
25ce0 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48  r SQLITE_OPEN_SH
25cf0 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a  AREDCACHE flag..
25d00 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70  **.**  <li> <b>p
25d10 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73  sow</b>: ^The ps
25d20 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64  ow parameter ind
25d30 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20 6f  icates whether o
25d40 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20  r not the.**    
25d50 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72   [powersafe over
25d60 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20  write] property 
25d70 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74  does or does not
25d80 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a   apply to the.**
25d90 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64       storage med
25da0 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20  ia on which the 
25db0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65  database file re
25dc0 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  sides..**.**  <l
25dd0 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e  i> <b>nolock</b>
25de0 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61  : ^The nolock pa
25df0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
25e00 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d  lean query param
25e10 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63  eter.**     whic
25e20 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65  h if set disable
25e30 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69  s file locking i
25e40 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e  n rollback journ
25e50 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a  al modes.  This.
25e60 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 6c  **     is useful
25e70 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61   for accessing a
25e80 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66   database on a f
25e90 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 64  ilesystem that d
25ea0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73  oes not.**     s
25eb0 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20  upport locking. 
25ec0 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62   Caution:  Datab
25ed0 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d  ase corruption m
25ee0 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 74  ight result if t
25ef0 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72  wo.**     or mor
25f00 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 74  e processes writ
25f10 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  e to the same da
25f20 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f  tabase and any o
25f30 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20  ne of those.**  
25f40 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65     processes use
25f50 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a  s nolock=1..**.*
25f60 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74  *  <li> <b>immut
25f70 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69  able</b>: ^The i
25f80 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74  mmutable paramet
25f90 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
25fa0 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72  query.**     par
25fb0 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 69  ameter that indi
25fc0 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 64  cates that the d
25fd0 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
25fe0 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20  stored on.**    
25ff0 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
26000 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62  .  ^When immutab
26010 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74  le is set, SQLit
26020 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
26030 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61  he.**     databa
26040 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62  se file cannot b
26050 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20  e changed, even 
26060 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 74  by a process wit
26070 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20  h higher.**     
26080 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73  privilege, and s
26090 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  o the database i
260a0 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e  s opened read-on
260b0 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69  ly and all locki
260c0 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68  ng.**     and ch
260d0 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69  ange detection i
260e0 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75  s disabled.  Cau
260f0 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68  tion: Setting th
26100 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20  e immutable.**  
26110 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61     property on a
26120 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
26130 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74  hat does in fact
26140 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75   change can resu
26150 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63  lt.**     in inc
26160 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65 73  orrect query res
26170 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  ults and/or [SQL
26180 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72  ITE_CORRUPT] err
26190 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20  ors..**     See 
261a0 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
261b0 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a  CAP_IMMUTABLE]..
261c0 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75  **       .** </u
261d0 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66  l>.**.** ^Specif
261e0 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20  ying an unknown 
261f0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
26200 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
26210 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74   of a URI is not
26220 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46   an.** error.  F
26230 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
26240 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75  f SQLite might u
26250 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69  nderstand additi
26260 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61  onal query.** pa
26270 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22  rameters.  See "
26280 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72  [query parameter
26290 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d  s with special m
262a0 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65  eaning to SQLite
262b0 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  ]" for.** additi
262c0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
262d0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
262e0 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d  lename examples]
262f0 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61  ] <h3>URI filena
26300 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e  me examples</h3>
26310 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  .**.** <table bo
26320 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63  rder="1" align=c
26330 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e  enter cellpaddin
26340 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  g=5>.** <tr><th>
26350 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c   URI filenames <
26360 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c  th> Results.** <
26370 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
26380 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
26390 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
263a0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
263b0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
263c0 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e  rectory..** <tr>
263d0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
263e0 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e  fred/data.db<br>
263f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
26400 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  e:///home/fred/d
26410 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20  ata.db <br> .** 
26420 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
26430 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66  localhost/home/f
26440 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
26450 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
26460 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61     Open the data
26470 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65  base file "/home
26480 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a  /fred/data.db"..
26490 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
264a0 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65  ://darkstar/home
264b0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74  /fred/data.db <t
264c0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
264d0 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73  An error. "darks
264e0 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65  tar" is not a re
264f0 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69  cognized authori
26500 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73  ty..** <tr><td s
26510 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63  tyle="white-spac
26520 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20  e:nowrap"> .**  
26530 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
26540 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61  C:/Documents%20a
26550 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72  nd%20Settings/fr
26560 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e  ed/Desktop/data.
26570 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57  db.**     <td> W
26580 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65  indows only: Ope
26590 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
265a0 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64  .db" on fred's d
265b0 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a  esktop on drive.
265c0 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20  **          C:. 
265d0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32  Note that the %2
265e0 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68  0 escaping in th
265f0 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f  is example is no
26600 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20  t strictly .**  
26610 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72          necessar
26620 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63  y - space charac
26630 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  ters can be used
26640 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20   literally.**   
26650 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69         in URI fi
26660 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e  lenames..** <tr>
26670 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
26680 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d  b?mode=ro&cache=
26690 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a  private <td> .**
266a0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
266b0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
266c0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
266d0 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d  ectory for read-
266e0 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20  only access..** 
266f0 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c           Regardl
26700 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
26710 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63  r not shared-cac
26720 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c  he mode is enabl
26730 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
26740 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61    default, use a
26750 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a   private cache..
26760 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
26770 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
26780 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74  .db?vfs=unix-dot
26790 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20  file <td>.**    
267a0 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
267b0 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
267c0 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70  .db". Use the sp
267d0 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d  ecial VFS "unix-
267e0 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20  dotfile".**     
267f0 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20 64       that uses d
26800 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63  ot-files in plac
26810 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73  e of posix advis
26820 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20  ory locking..** 
26830 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
26840 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f  ta.db?mode=reado
26850 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  nly <td> .**    
26860 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
26870 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f  "readonly" is no
26880 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e  t a valid option
26890 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20   for the "mode" 
268a0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f  parameter..** </
268b0 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52  table>.**.** ^UR
268c0 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  I hexadecimal es
268d0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28  cape sequences (
268e0 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74  %HH) are support
268f0 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61  ed within the pa
26900 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20  th and.** query 
26910 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20  components of a 
26920 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d  URI. A hexadecim
26930 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
26940 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61  ce consists of a
26950 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e  .** percent sign
26960 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65   - "%" - followe
26970 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f  d by exactly two
26980 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67   hexadecimal dig
26990 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69  its .** specifyi
269a0 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75  ng an octet valu
269b0 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70  e. ^Before the p
269c0 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d  ath or query com
269d0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20  ponents of a.** 
269e0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65  URI filename are
269f0 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68   interpreted, th
26a00 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75  ey are encoded u
26a10 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61  sing UTF-8 and a
26a20 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d  ll .** hexadecim
26a30 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
26a40 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20  ces replaced by 
26a50 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f  a single byte co
26a60 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
26a70 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63  corresponding oc
26a80 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f  tet. If this pro
26a90 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61  cess generates a
26aa0 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20  n invalid UTF-8 
26ab0 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65  encoding,.** the
26ac0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
26ad0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  efined..**.** <b
26ae0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
26af0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
26b00 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
26b10 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
26b20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
26b30 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
26b40 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
26b50 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
26b60 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
26b70 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
26b80 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
26b90 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
26ba0 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
26bb0 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
26bc0 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
26bd0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
26be0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
26bf0 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
26c00 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
26c10 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
26c20 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
26c30 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  to Windows Runti
26c40 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  me users:</b>  T
26c50 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72  he temporary dir
26c60 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73  ectory must be s
26c70 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63  et.** prior to c
26c80 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f  alling sqlite3_o
26c90 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
26ca0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68  _open_v2().  Oth
26cb0 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a  erwise, various.
26cc0 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74  ** features that
26cd0 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65   require the use
26ce0 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69   of temporary fi
26cf0 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a  les may fail..**
26d00 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
26d10 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
26d20 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45  ctory].*/.SQLITE
26d30 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
26d40 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  APICALL sqlite3_
26d50 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
26d60 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
26d70 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
26d80 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
26d90 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
26da0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
26db0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
26dc0 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  le */.);.SQLITE_
26dd0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41  API int SQLITE_A
26de0 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f  PICALL sqlite3_o
26df0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
26e00 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
26e10 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
26e20 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
26e30 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
26e40 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
26e50 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
26e60 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  ndle */.);.SQLIT
26e70 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
26e80 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33  _APICALL sqlite3
26e90 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
26ea0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
26eb0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
26ec0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
26ed0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
26ee0 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
26ef0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
26f00 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
26f10 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
26f20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
26f30 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
26f40 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
26f50 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
26f60 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
26f70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
26f80 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
26f90 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
26fa0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
26fb0 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
26fc0 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
26fd0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
26fe0 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
26ff0 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
27000 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
27010 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
27020 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
27030 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
27040 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
27050 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
27060 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
27070 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
27080 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
27090 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
270a0 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
270b0 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
270c0 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
270d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
270e0 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
270f0 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
27100 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
27110 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
27120 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
27130 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
27140 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
27150 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
27160 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
27170 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
27180 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
27190 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
271a0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
271b0 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
271c0 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
271d0 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
271e0 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
271f0 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
27200 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
27210 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
27220 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
27230 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
27240 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
27250 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
27260 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
27270 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
27280 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
27290 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
272a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
272b0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
272c0 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
272d0 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
272e0 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
272f0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
27300 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
27310 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
27320 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
27330 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
27340 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
27350 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
27360 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
27370 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
27380 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
27390 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
273a0 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
273b0 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
273c0 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
273d0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
273e0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
273f0 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
27400 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
27410 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
27420 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
27430 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
27440 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
27450 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
27460 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
27470 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
27480 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
27490 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
274a0 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
274b0 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
274c0 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
274d0 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
274e0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
274f0 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
27500 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
27510 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then sqli
27520 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
27530 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28  F,P,B) returns (
27540 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
27550 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
27560 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
27570 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
27580 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
27590 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
275a0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
275b0 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
275c0 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
275d0 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
275e0 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
275f0 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
27600 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
27610 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
27620 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
27630 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
27640 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
27650 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
27660 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
27670 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
27680 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
27690 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
276a0 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
276b0 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
276c0 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
276d0 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
276e0 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
276f0 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
27700 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
27710 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
27720 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
27730 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
27740 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
27750 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
27760 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
27770 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
27780 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
27790 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69  ITE_APICALL sqli
277a0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
277b0 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
277c0 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
277d0 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51  har *zParam);.SQ
277e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
277f0 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69  ITE_APICALL sqli
27800 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
27810 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
27820 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
27830 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61  Param, int bDefa
27840 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ult);.SQLITE_API
27850 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53   sqlite3_int64 S
27860 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71  QLITE_APICALL sq
27870 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
27880 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e  const char*, con
27890 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
278a0 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a  3_int64);.../*.*
278b0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
278c0 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
278d0 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ages.** METHOD: 
278e0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49  sqlite3.**.** ^I
278f0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
27900 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  t sqlite3_* API 
27910 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20  call associated 
27920 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61  with .** [databa
27930 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
27940 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68   failed, then th
27950 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
27960 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  e(D) interface.*
27970 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  * returns the nu
27980 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
27990 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  de] or [extended
279a0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
279b0 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61  r that.** API ca
279c0 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f  ll..** If the mo
279d0 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
279e0 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73 66 75  ll was successfu
279f0 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  l,.** then the r
27a00 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
27a10 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
27a20 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
27a30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27a40 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
27a50 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
27a60 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
27a70 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
27a80 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
27a90 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
27aa0 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
27ab0 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
27ac0 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
27ad0 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
27ae0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
27af0 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
27b00 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
27b10 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
27b20 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
27b30 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
27b40 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
27b50 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
27b60 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
27b70 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
27b80 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
27b90 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
27ba0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
27bb0 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
27bc0 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
27bd0 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
27be0 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
27bf0 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
27c00 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
27c10 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
27c20 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
27c30 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
27c40 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
27c50 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
27c60 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
27c70 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ons.)^.**.** ^Th
27c80 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72  e sqlite3_errstr
27c90 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
27ca0 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68  urns the English
27cb0 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a  -language text.*
27cc0 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  * that describes
27cd0 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64   the [result cod
27ce0 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a  e], as UTF-8..**
27cf0 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
27d00 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
27d10 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
27d20 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
27d30 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74  .** and must not
27d40 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65   be freed by the
27d50 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a   application)^..
27d60 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73  **.** When the s
27d70 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
27d80 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e  ding mode] is in
27d90 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62   use, it might b
27da0 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68  e the.** case th
27db0 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f  at a second erro
27dc0 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65  r occurs on a se
27dd0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e  parate thread in
27de0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
27df0 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73  time of the firs
27e00 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20  t error and the 
27e10 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e  call to these in
27e20 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65  terfaces..** Whe
27e30 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20  n that happens, 
27e40 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  the second error
27e50 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65   will be reporte
27e60 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a  d since these.**
27e70 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61   interfaces alwa
27e80 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f  ys report the mo
27e90 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74  st recent result
27ea0 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  .  To avoid.** t
27eb0 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64  his, each thread
27ec0 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c   can obtain excl
27ed0 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65  usive use of the
27ee0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
27ef0 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69  ction] D.** by i
27f00 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
27f10 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73  _mutex_enter]([s
27f20 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
27f30 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69  (D)) before begi
27f40 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20  nning.** to use 
27f50 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b  D and invoking [
27f60 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
27f70 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ave]([sqlite3_db
27f80 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65  _mutex](D)) afte
27f90 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74  r.** all calls t
27fa0 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  o the interfaces
27fb0 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65   listed here are
27fc0 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a   completed..**.*
27fd0 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
27fe0 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
27ff0 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
28000 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
28010 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
28020 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
28030 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
28040 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
28050 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
28060 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
28070 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
28080 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54  be set..*/.SQLIT
28090 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
280a0 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33  _APICALL sqlite3
280b0 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
280c0 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50   *db);.SQLITE_AP
280d0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 49  I int SQLITE_API
280e0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 74  CALL sqlite3_ext
280f0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
28100 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49  lite3 *db);.SQLI
28110 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
28120 72 20 2a 53 51 4c 49 54 45 5f 41 50 49 43 41 4c  r *SQLITE_APICAL
28130 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  L sqlite3_errmsg
28140 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
28150 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
28160 64 20 2a 53 51 4c 49 54 45 5f 41 50 49 43 41 4c  d *SQLITE_APICAL
28170 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  L sqlite3_errmsg
28180 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  16(sqlite3*);.SQ
28190 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
281a0 68 61 72 20 2a 53 51 4c 49 54 45 5f 41 50 49 43  har *SQLITE_APIC
281b0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 73  ALL sqlite3_errs
281c0 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  tr(int);../*.** 
281d0 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72  CAPI3REF: Prepar
281e0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
281f0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
28200 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
28210 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
28220 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
28230 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
28240 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
28250 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
28260 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
28270 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20  hat.** has been 
28280 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69  compiled into bi
28290 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73  nary form and is
282a0 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61   ready to be eva
282b0 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  luated..**.** Th
282c0 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20  ink of each SQL 
282d0 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73  statement as a s
282e0 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72  eparate computer
282f0 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a   program.  The.*
28300 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
28310 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f  ext is source co
28320 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20  de.  A prepared 
28330 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
28340 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70   .** is the comp
28350 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65  iled object code
28360 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20  .  All SQL must 
28370 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  be converted int
28380 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  o a.** prepared 
28390 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65  statement before
283a0 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a   it can be run..
283b0 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63  **.** The life-c
283c0 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72  ycle of a prepar
283d0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
283e0 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73  ect usually goes
283f0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
28400 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
28410 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72  reate the prepar
28420 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
28430 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
28440 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
28450 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76  ..** <li> Bind v
28460 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65  alues to [parame
28470 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
28480 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
28490 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
284a0 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
284b0 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
284c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
284d0 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
284e0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
284f0 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  Reset the prepar
28500 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
28510 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
28520 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
28530 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
28540 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
28550 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
28560 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
28570 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
28580 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
28590 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
285a0 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  >.*/.typedef str
285b0 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  uct sqlite3_stmt
285c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a   sqlite3_stmt;..
285d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
285e0 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a  Run-time Limits.
285f0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
28600 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e3.**.** ^(This 
28610 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
28620 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
28630 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
28640 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
28650 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
28660 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
28670 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
28680 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
28690 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
286a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
286b0 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
286c0 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
286d0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
286e0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
286f0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
28700 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
28710 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
28720 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
28730 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
28740 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
28750 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
28760 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
28770 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29  that construct.)
28780 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
28790 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
287a0 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
287b0 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
287c0 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
287d0 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65   each limit cate
287e0 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49  gory SQLITE_LIMI
287f0 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68  T_<i>NAME</i> th
28800 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69  ere is a .** [li
28810 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65  mits | hard uppe
28820 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20  r bound].** set 
28830 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
28840 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73  by a C preproces
28850 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64  sor macro called
28860 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51  .** [limits | SQ
28870 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45  LITE_MAX_<i>NAME
28880 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22  </i>]..** (The "
28890 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
288a0 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
288b0 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a  to "_MAX_".))^.*
288c0 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69  * ^Attempts to i
288d0 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
288e0 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
288f0 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
28900 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
28910 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
28920 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a   upper bound..**
28930 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
28940 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
28950 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
28960 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a  changed, the .**
28970 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
28980 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
28990 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76  urns the prior v
289a0 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
289b0 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f  t..** ^Hence, to
289c0 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e   find the curren
289d0 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d  t value of a lim
289e0 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  it without chang
289f0 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c  ing it,.** simpl
28a00 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e  y invoke this in
28a10 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65  terface with the
28a20 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
28a30 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a   set to -1..**.*
28a40 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
28a50 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
28a60 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
28a70 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
28a80 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
28a90 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
28aa0 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
28ab0 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
28ac0 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
28ad0 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
28ae0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
28af0 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
28b00 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
28b10 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
28b20 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
28b30 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
28b40 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
28b50 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
28b60 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
28b70 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
28b80 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
28b90 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
28ba0 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
28bb0 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
28bc0 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
28bd0 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
28be0 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
28bf0 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
28c00 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
28c10 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
28c20 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
28c30 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
28c40 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
28c50 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
28c60 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
28c70 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
28c80 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
28c90 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
28ca0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
28cb0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
28cc0 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
28cd0 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
28ce0 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
28cf0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
28d00 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
28d10 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
28d20 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
28d30 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
28d40 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
28d50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
28d60 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
28d70 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
28d80 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
28d90 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
28da0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
28db0 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71  QLITE_APICALL sq
28dc0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
28dd0 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
28de0 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
28df0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
28e00 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
28e10 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ories.** KEYWORD
28e20 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
28e30 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65  ry} {*limit cate
28e40 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
28e50 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
28e60 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72  fine various per
28e70 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a  formance limits.
28e80 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
28e90 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69  owered at run-ti
28ea0 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  me using [sqlite
28eb0 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
28ec0 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74  he synopsis of t
28ed0 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
28ee0 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
28ef0 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  s is shown below
28f00 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
28f10 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61  information is a
28f20 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d  vailable at [lim
28f30 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20  its | Limits in 
28f40 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  SQLite]..**.** <
28f50 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
28f60 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e  LIMIT_LENGTH]] ^
28f70 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
28f80 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
28f90 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
28fa0 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
28fb0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
28fc0 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74  able row, in byt
28fd0 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  es.<dd>)^.**.** 
28fe0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  [[SQLITE_LIMIT_S
28ff0 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  QL_LENGTH]] ^(<d
29000 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
29010 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
29020 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29030 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
29040 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
29050 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
29060 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
29070 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c  MIT_COLUMN]] ^(<
29080 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29090 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
290a0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
290b0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
290c0 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
290d0 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
290e0 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
290f0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
29100 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
29110 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
29120 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
29130 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
29140 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
29150 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
29160 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  [[SQLITE_LIMIT_E
29170 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  XPR_DEPTH]] ^(<d
29180 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
29190 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
291a0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
291b0 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
291c0 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
291d0 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
291e0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
291f0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
29200 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74  D_SELECT]] ^(<dt
29210 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
29220 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
29230 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
29240 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
29250 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
29260 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
29270 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ment.</dd>)^.**.
29280 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29290 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64  T_VDBE_OP]] ^(<d
292a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
292b0 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
292c0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
292d0 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
292e0 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
292f0 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
29300 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
29310 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
29320 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20  tatement.  This 
29330 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72  limit is not cur
29340 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63  rently.** enforc
29350 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20  ed, though that 
29360 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69  might be added i
29370 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
29380 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
29390 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  te.</dd>)^.**.**
293a0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
293b0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e  FUNCTION_ARG]] ^
293c0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
293d0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
293e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
293f0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
29400 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
29410 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
29420 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
29430 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d  LIMIT_ATTACHED]]
29440 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29450 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
29460 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29470 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
29480 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
29490 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
294a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
294b0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
294c0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a  ATTERN_LENGTH]].
294d0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
294e0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
294f0 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
29500 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29510 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
29520 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
29530 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
29540 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
29550 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
29560 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29570 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
29580 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ER]].** ^(<dt>SQ
29590 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
295a0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
295b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
295c0 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20  um index number 
295d0 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65  of any [paramete
295e0 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  r] in an SQL sta
295f0 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  tement.)^.**.** 
29600 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  [[SQLITE_LIMIT_T
29610 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e  RIGGER_DEPTH]] ^
29620 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
29630 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
29640 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29650 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
29660 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
29670 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a  riggers.</dd>)^.
29680 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29690 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
296a0 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ADS]] ^(<dt>SQLI
296b0 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
296c0 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20  THREADS</dt>.** 
296d0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
296e0 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69  number of auxili
296f0 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61  ary worker threa
29700 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65  ds that a single
29710 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
29720 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61  atement] may sta
29730 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rt.</dd>)^.** </
29740 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
29750 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
29760 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
29770 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
29780 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
29790 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
297a0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
297b0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
297c0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
297d0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
297e0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
297f0 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
29800 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
29810 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29820 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
29830 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
29840 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29850 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
29860 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
29870 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29880 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
29890 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
298a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
298b0 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
298c0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
298d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
298e0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
298f0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
29900 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29910 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
29920 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
29930 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29940 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
29950 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
29960 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
29970 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
29980 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20  READS           
29990 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  11../*.** CAPI3R
299a0 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
299b0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
299c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
299d0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
299e0 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ler}.** METHOD: 
299f0 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54  sqlite3.** CONST
29a00 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f  RUCTOR: sqlite3_
29a10 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  stmt.**.** To ex
29a20 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
29a30 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
29a40 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
29a50 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
29a60 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
29a70 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
29a80 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
29a90 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
29aa0 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
29ab0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29ac0 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
29ad0 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65  a.** prior succe
29ae0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
29af0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
29b00 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
29b10 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
29b20 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54  e3_open16()].  T
29b30 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
29b40 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
29b50 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64  have been closed
29b60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
29b70 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
29b80 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
29b90 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
29ba0 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
29bb0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
29bc0 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
29bd0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
29be0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
29bf0 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
29c00 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54  nterfaces use UT
29c10 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  F-8, and sqlite3
29c20 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
29c30 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
29c40 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
29c50 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
29c60 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
29c70 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ent is negative,
29c80 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
29c90 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
29ca0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
29cb0 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
29cc0 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68   is positive, th
29cd0 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20  en it is the.** 
29ce0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
29cf0 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
29d00 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65   ^If nByte is ze
29d10 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70  ro, then no prep
29d20 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
29d30 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a  t is generated..
29d40 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  ** If the caller
29d50 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20   knows that the 
29d60 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
29d70 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
29d80 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65  d, then.** there
29d90 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66   is a small perf
29da0 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
29db0 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20  e to passing an 
29dc0 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
29dd0 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e  that.** is the n
29de0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
29df0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
29e00 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
29e10 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
29e20 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
29e30 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e   ^If pzTail is n
29e40 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a  ot NULL then *pz
29e50 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
29e60 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72  point to the fir
29e70 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20  st byte.** past 
29e80 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
29e90 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
29ea0 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65  nt in zSql.  The
29eb0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79  se routines only
29ec0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  .** compile the 
29ed0 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20  first statement 
29ee0 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
29ef0 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
29f00 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20  ting to.** what 
29f10 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c  remains uncompil
29f20 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74  ed..**.** ^*ppSt
29f30 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  mt is left point
29f40 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65  ing to a compile
29f50 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
29f60 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20  ement] that can 
29f70 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75  be.** executed u
29f80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
29f90 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72  ep()].  ^If ther
29fa0 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
29fb0 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a  ppStmt is set.**
29fc0 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74   to NULL.  ^If t
29fd0 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
29fe0 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
29ff0 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
2a000 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e  n empty.** strin
2a010 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
2a020 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
2a030 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
2a040 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63  The calling proc
2a050 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73  edure is respons
2a060 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e  ible for deletin
2a070 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a  g the compiled.*
2a080 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
2a090 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
2a0a0 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72  inalize()] after
2a0b0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
2a0c0 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53   with it..** ppS
2a0d0 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e  tmt may not be N
2a0e0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73  ULL..**.** ^On s
2a0f0 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69  uccess, the sqli
2a100 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61  te3_prepare() fa
2a110 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73  mily of routines
2a120 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2a130 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73  OK];.** otherwis
2a140 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
2a150 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
2a160 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2a170 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e  _prepare_v2() an
2a180 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2a190 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61  e16_v2() interfa
2a1a0 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d  ces are.** recom
2a1b0 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e  mended for all n
2a1c0 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65  ew programs. The
2a1d0 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72   two older inter
2a1e0 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e  faces are retain
2a1f0 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61  ed.** for backwa
2a200 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
2a210 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
2a220 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
2a230 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22  .** ^In the "v2"
2a240 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
2a250 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2a260 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
2a270 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
2a280 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
2a290 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
2a2a0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
2a2b0 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
2a2c0 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
2a2d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2a2e0 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
2a2f0 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65  * behave differe
2a300 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61  ntly in three wa
2a310 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
2a320 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
2a330 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
2a340 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
2a350 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
2a360 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
2a370 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
2a380 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
2a390 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
2a3a0 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2a3b0 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
2a3c0 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
2a3d0 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
2a3e0 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20   again. As many 
2a3f0 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53  as [SQLITE_MAX_S
2a400 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20  CHEMA_RETRY].** 
2a410 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63  retries will occ
2a420 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  ur before sqlite
2a430 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75  3_step() gives u
2a440 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e  p and returns an
2a450 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e   error..** </li>
2a460 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
2a470 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
2a480 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
2a490 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
2a4a0 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
2a4b0 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
2a4c0 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
2a4d0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
2a4e0 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20  ].  ^The legacy 
2a4f0 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
2a500 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
2a510 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
2a520 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
2a530 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
2a540 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
2a550 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
2a560 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74  ion would have t
2a570 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
2a580 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2a590 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20  _reset()].** in 
2a5a0 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
2a5b0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
2a5c0 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
2a5d0 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
2a5e0 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
2a5f0 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
2a600 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
2a610 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
2a620 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
2a630 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
2a640 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
2a650 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  the specific val
2a660 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72  ue bound to [par
2a670 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61  ameter | host pa
2a680 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
2a690 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
2a6a0 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
2a6b0 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71   the choice of q
2a6c0 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20  uery plan for a 
2a6d0 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68  statement,.** th
2a6e0 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
2a6f0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
2a700 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
2a710 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68  d, as if there h
2a720 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63  ad been .** a sc
2a730 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20  hema change, on 
2a740 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69  the first  [sqli
2a750 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
2a760 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63   following any c
2a770 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20  hange.** to the 
2a780 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
2a790 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  xt | bindings] o
2a7a0 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65  f that [paramete
2a7b0 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65  r]. .** ^The spe
2a7c0 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57  cific value of W
2a7d0 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72  HERE-clause [par
2a7e0 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e  ameter] might in
2a7f0 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20  fluence the .** 
2a800 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
2a810 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61  plan if the para
2a820 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66  meter is the lef
2a830 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61  t-hand side of a
2a840 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47   [LIKE].** or [G
2a850 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72  LOB] operator or
2a860 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2a870 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f  r is compared to
2a880 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75   an indexed colu
2a890 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53  mn.** and the [S
2a8a0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41  QLITE_ENABLE_STA
2a8b0 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  T3] compile-time
2a8c0 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
2a8d0 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ed..** </li>.** 
2a8e0 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  </ol>.*/.SQLITE_
2a8f0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41  API int SQLITE_A
2a900 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70  PICALL sqlite3_p
2a910 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
2a920 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2a930 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2a940 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2a950 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
2a960 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2a970 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
2a980 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2a990 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2a9a0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2a9b0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2a9c0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2a9d0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2a9e0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2a9f0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2aa00 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2aa10 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2aa20 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2aa30 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2aa40 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
2aa50 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43   int SQLITE_APIC
2aa60 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70  ALL sqlite3_prep
2aa70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
2aa80 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2aa90 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2aaa0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2aab0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
2aac0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2aad0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
2aae0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2aaf0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2ab00 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2ab10 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2ab20 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2ab30 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2ab40 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2ab50 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2ab60 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2ab70 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2ab80 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2ab90 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2aba0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
2abb0 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43   int SQLITE_APIC
2abc0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70  ALL sqlite3_prep
2abd0 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
2abe0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2abf0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2ac00 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2ac10 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2ac20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2ac30 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2ac40 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2ac50 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2ac60 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2ac70 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2ac80 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2ac90 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2aca0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2acb0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2acc0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
2acd0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2ace0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2acf0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2ad00 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
2ad10 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43   int SQLITE_APIC
2ad20 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70  ALL sqlite3_prep
2ad30 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69  are16_v2(.  sqli
2ad40 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2ad50 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2ad60 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2ad70 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
2ad80 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2ad90 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
2ada0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2adb0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2adc0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2add0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2ade0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2adf0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2ae00 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2ae10 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2ae20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
2ae30 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2ae40 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2ae50 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2ae60 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ql */.);../*.** 
2ae70 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65  CAPI3REF: Retrie
2ae80 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53  ving Statement S
2ae90 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  QL.** METHOD: sq
2aea0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2aeb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71   ^The sqlite3_sq
2aec0 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  l(P) interface r
2aed0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2aee0 20 74 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68   to a copy of th
2aef0 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74  e UTF-8.** SQL t
2af00 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
2af10 74 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  te [prepared sta
2af20 74 65 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77  tement] P if P w
2af30 61 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  as.** created by
2af40 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
2af50 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2af60 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2af70 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e  re16_v2()]..** ^
2af80 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61  The sqlite3_expa
2af90 6e 64 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65  nded_sql(P) inte
2afa0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2afb0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46  pointer to a UTF
2afc0 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  -8.** string con
2afd0 74 61 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20  taining the SQL 
2afe0 74 65 78 74 20 6f 66 20 70 72 65 70 61 72 65 64  text of prepared
2aff0 20 73 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74   statement P wit
2b000 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61  h.** [bound para
2b010 6d 65 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64  meters] expanded
2b020 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  ..**.** ^(For ex
2b030 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 72 65 70  ample, if a prep
2b040 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2b050 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  s created using 
2b060 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20  the SQL.** text 
2b070 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79  "SELECT $abc,:xy
2b080 7a 22 20 61 6e 64 20 69 66 20 70 61 72 61 6d 65  z" and if parame
2b090 74 65 72 20 24 61 62 63 20 69 73 20 62 6f 75 6e  ter $abc is boun
2b0a0 64 20 74 6f 20 69 6e 74 65 67 65 72 20 32 33 34  d to integer 234
2b0b0 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65 74  5.** and paramet
2b0c0 65 72 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75  er :xyz is unbou
2b0d0 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  nd, then sqlite3
2b0e0 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 65 74 75  _sql() will retu
2b0f0 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  rn.** the origin
2b100 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 45 4c 45  al string, "SELE
2b110 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 62 75  CT $abc,:xyz" bu
2b120 74 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  t sqlite3_expand
2b130 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c  ed_sql().** will
2b140 20 72 65 74 75 72 6e 20 22 53 45 4c 45 43 54 20   return "SELECT 
2b150 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a  2345,NULL".)^.**
2b160 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b170 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20  _expanded_sql() 
2b180 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2b190 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66  s NULL if insuff
2b1a0 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a  icient memory.**
2b1b0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f   is available to
2b1c0 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
2b1d0 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 73 75  , or if the resu
2b1e0 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20  lt would exceed 
2b1f0 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d  the.** the maxim
2b200 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67 74 68  um string length
2b210 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
2b220 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  he [SQLITE_LIMIT
2b230 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20  _LENGTH]..**.** 
2b240 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  ^The [SQLITE_TRA
2b250 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63  CE_SIZE_LIMIT] c
2b260 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
2b270 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69  on limits the si
2b280 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70  ze of.** bound p
2b290 61 72 61 6d 65 74 65 72 20 65 78 70 61 6e 73 69  arameter expansi
2b2a0 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  ons.  ^The [SQLI
2b2b0 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63  TE_OMIT_TRACE] c
2b2c0 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
2b2d0 70 74 69 6f 6e 20 63 61 75 73 65 73 20 73 71 6c  ption causes sql
2b2e0 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2b2f0 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 20 72 65  l() to always re
2b300 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  turn NULL..**.**
2b310 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65 74   ^The string ret
2b320 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2b330 5f 73 71 6c 28 50 29 20 69 73 20 6d 61 6e 61 67  _sql(P) is manag
2b340 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64  ed by SQLite and
2b350 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   is.** automatic
2b360 61 6c 6c 79 20 66 72 65 65 64 20 77 68 65 6e 20  ally freed when 
2b370 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2b380 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69  tement is finali
2b390 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72  zed..** ^The str
2b3a0 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20  ing returned by 
2b3b0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2b3c0 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20  _sql(P), on the 
2b3d0 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69  other hand,.** i
2b3e0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
2b3f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2b400 29 5d 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66  )] and must be f
2b410 72 65 65 20 62 79 20 74 68 65 20 61 70 70 6c 69  ree by the appli
2b420 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73  cation.** by pas
2b430 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
2b440 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a  te3_free()]..*/.
2b450 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2b460 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 41 50   char *SQLITE_AP
2b470 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 71  ICALL sqlite3_sq
2b480 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
2b490 70 53 74 6d 74 29 3b 0a 53 51 4c 49 54 45 5f 41  pStmt);.SQLITE_A
2b4a0 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  PI char *SQLITE_
2b4b0 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  APICALL sqlite3_
2b4c0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c  expanded_sql(sql
2b4d0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2b4e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b4f0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
2b500 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2b510 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
2b520 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a  abase.** METHOD:
2b530 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2b540 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b550 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
2b560 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2b570 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
2b580 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
2b590 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
2b5a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
2b5b0 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
2b5c0 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
2b5d0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2b5e0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
2b5f0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2b600 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2b610 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2b620 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
2b630 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
2b640 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
2b650 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
2b660 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
2b670 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
2b680 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
2b690 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
2b6a0 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
2b6b0 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
2b6c0 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
2b6d0 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
2b6e0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
2b6f0 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
2b700 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2b710 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
2b720 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
2b730 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
2b740 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
2b750 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
2b760 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
2b770 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
2b780 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
2b790 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
2b7a0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2b7b0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
2b7c0 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
2b7d0 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
2b7e0 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
2b7f0 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
2b800 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
2b810 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
2b820 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
2b830 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
2b840 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
2b850 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
2b860 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
2b870 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
2b880 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
2b890 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
2b8a0 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
2b8b0 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
2b8c0 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
2b8d0 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
2b8e0 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
2b8f0 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
2b900 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
2b910 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
2b920 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
2b930 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
2b940 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
2b950 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
2b960 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
2b970 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
2b980 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
2b990 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
2b9a0 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
2b9b0 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
2b9c0 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
2b9d0 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
2b9e0 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
2b9f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
2ba00 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
2ba10 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
2ba20 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2ba30 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
2ba40 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49  on disk..*/.SQLI
2ba50 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2ba60 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65  E_APICALL sqlite
2ba70 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2ba80 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2ba90 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2baa0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2bab0 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53   If A Prepared S
2bac0 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65  tatement Has Bee
2bad0 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  n Reset.** METHO
2bae0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2baf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2bb00 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20  e3_stmt_busy(S) 
2bb10 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2bb20 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
2bb30 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ) if the.** [pre
2bb40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2bb50 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70   S has been step
2bb60 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  ped at least onc
2bb70 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  e using .** [sql
2bb80 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75  ite3_step(S)] bu
2bb90 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75  t has neither ru
2bba0 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
2bbb0 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51  (returned.** [SQ
2bbc0 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20  LITE_DONE] from 
2bbd0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2bbe0 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72  ]) nor.** been r
2bbf0 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  eset using [sqli
2bc00 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20  te3_reset(S)].  
2bc10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2bc20 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74  t_busy(S).** int
2bc30 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66  erface returns f
2bc40 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e  alse if S is a N
2bc50 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66  ULL pointer.  If
2bc60 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20   S is not a .** 
2bc70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
2bc80 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65   is not a pointe
2bc90 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72  r to a valid [pr
2bca0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2bcb0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65  ].** object, the
2bcc0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
2bcd0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
2bce0 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72  probably undesir
2bcf0 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  able..**.** This
2bd00 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
2bd10 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e  e used in combin
2bd20 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e  ation [sqlite3_n
2bd30 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74  ext_stmt()].** t
2bd40 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65  o locate all pre
2bd50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2bd60 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2bd70 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20   a database .** 
2bd80 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
2bd90 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62  are in need of b
2bda0 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69  eing reset.  Thi
2bdb0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a  s can be used,.*
2bdc0 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  * for example, i
2bdd0 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75  n diagnostic rou
2bde0 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20  tines to search 
2bdf0 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a  for prepared .**
2be00 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
2be10 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74   are holding a t
2be20 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e  ransaction open.
2be30 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2be40 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c  nt SQLITE_APICAL
2be50 4c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  L sqlite3_stmt_b
2be60 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  usy(sqlite3_stmt
2be70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2be80 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
2be90 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
2bea0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
2beb0 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
2bec0 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
2bed0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2bee0 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
2bef0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
2bf00 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2bf10 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
2bf20 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
2bf30 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
2bf40 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
2bf50 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
2bf60 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
2bf70 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
2bf80 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56  s it stores.  ^V
2bf90 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
2bfa0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2bfb0 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
2bfc0 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
2bfd0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
2bfe0 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
2bff0 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
2c000 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
2c010 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
2c020 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
2c030 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
2c040 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
2c050 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
2c060 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2c070 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
2c080 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
2c090 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
2c0a0 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
2c0b0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
2c0c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
2c0d0 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
2c0e0 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
2c0f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
2c100 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
2c110 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
2c120 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
2c130 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2c140 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a  e3_value.  The.*
2c150 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
2c160 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63  _dup()] interfac
2c170 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
2c180 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77   construct a new
2c190 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73   .** protected s
2c1a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f  qlite3_value fro
2c1b0 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  m an unprotected
2c1c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2c1d0 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
2c1e0 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
2c1f0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
2c200 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
2c210 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
2c220 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e   is held.  An in
2c230 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
2c240 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
2c250 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2c260 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
2c270 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
2c280 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
2c290 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2c2a0 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
2c2b0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2c2c0 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
2c2d0 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
2c2e0 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  ith [SQLITE_THRE
2c2f0 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69  ADSAFE=0] and wi
2c300 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  th [sqlite3_thre
2c310 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e  adsafe()] return
2c320 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20  ing 0).** or if 
2c330 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e  SQLite is run in
2c340 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20   one of reduced 
2c350 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20  mutex modes .** 
2c360 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
2c370 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20  INGLETHREAD] or 
2c380 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2c390 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74  ULTITHREAD].** t
2c3a0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hen there is no 
2c3b0 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
2c3c0 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
2c3d0 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
2c3e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2c3f0 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20  bjects and they 
2c400 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65  can be used inte
2c410 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f  rchangeably.  Ho
2c420 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61  wever,.** for ma
2c430 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61  ximum code porta
2c440 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63  bility it is rec
2c450 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
2c460 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74  plications.** st
2c470 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73  ill make the dis
2c480 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
2c490 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
2c4a0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2c4b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2c4c0 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
2c4d0 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
2c4e0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
2c4f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2c500 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
2c510 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
2c520 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
2c530 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2c540 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
2c550 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2c560 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
2c570 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ted..** ^The sql
2c580 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c590 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2c5a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c5b0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
2c5c0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
2c5d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2c5e0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
2c5f0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2c600 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
2c610 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
2c620 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
2c630 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  nd_value()]..** 
2c640 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2c650 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
2c660 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
2c670 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
2c680 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2c690 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c6a0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
2c6b0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
2c6c0 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
2c6d0 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
2c6e0 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74  I3REF: SQL Funct
2c6f0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
2c700 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  ct.**.** The con
2c710 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
2c720 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
2c730 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
2c740 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
2c750 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
2c760 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f  .  ^A pointer to
2c770 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
2c780 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
2c790 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
2c7a0 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
2c7b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2c7c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
2c7d0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
2c7e0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2c7f0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2c800 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
2c810 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
2c820 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
2c830 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2c840 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
2c850 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
2c860 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
2c870 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
2c880 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
2c890 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
2c8a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2c8b0 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
2c8c0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
2c8d0 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
2c8e0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2c8f0 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
2c900 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2c910 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
2c920 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
2c930 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
2c940 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
2c950 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
2c960 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
2c970 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
2c980 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
2c990 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2c9a0 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
2c9b0 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
2c9c0 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
2c9d0 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
2c9e0 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48  binding}.** METH
2c9f0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2ca00 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20  .**.** ^(In the 
2ca10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
2ca20 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  xt input to [sql
2ca30 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2ca40 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
2ca50 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73  nts,.** literals
2ca60 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64   may be replaced
2ca70 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72   by a [parameter
2ca80 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f  ] that matches o
2ca90 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a  ne of following.
2caa0 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a  ** templates:.**
2cab0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2cac0 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
2cad0 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
2cae0 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
2caf0 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
2cb00 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
2cb10 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76  e templates abov
2cb20 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74  e, NNN represent
2cb30 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
2cb40 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
2cb50 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61   represents an a
2cb60 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e  lphanumeric iden
2cb70 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20  tifier.)^  ^The 
2cb80 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
2cb90 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
2cba0 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
2cbb0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
2cbc0 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
2cbd0 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
2cbe0 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
2cbf0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2cc00 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
2cc10 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   here..**.** ^Th
2cc20 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2cc30 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2cc40 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2cc50 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
2cc60 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2cc70 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
2cc80 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
2cc90 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
2cca0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2ccb0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
2ccc0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
2ccd0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2cce0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
2ccf0 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
2cd00 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  e set..** ^The l
2cd10 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
2cd20 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
2cd30 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20  ex of 1.  ^When 
2cd40 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
2cd50 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
2cd60 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
2cd70 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
2cd80 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
2cd90 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
2cda0 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
2cdb0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
2cdc0 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68  currence..** ^Th
2cdd0 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65  e index for name
2cde0 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e  d parameters can
2cdf0 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73   be looked up us
2ce00 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
2ce10 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2ce20 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20  er_index()] API 
2ce30 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68  if desired.  ^Th
2ce40 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
2ce50 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
2ce60 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
2ce70 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e   NNN..** ^The NN
2ce80 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
2ce90 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
2cea0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
2ceb0 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
2cec0 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
2ced0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
2cee0 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
2cef0 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  999)..**.** ^The
2cf00 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
2cf10 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
2cf20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
2cf30 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  meter..** ^If th
2cf40 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2cf50 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2cf60 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
2cf70 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2cf80 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2cf90 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61  bind_blob() is a
2cfa0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
2cfb0 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  en the fourth pa
2cfc0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67  rameter.** is ig
2cfd0 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e  nored and the en
2cfe0 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20  d result is the 
2cff0 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f  same as sqlite3_
2d000 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a  bind_null()..**.
2d010 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
2d020 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
2d030 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
2d040 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
2d050 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2d060 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
2d070 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
2d080 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
2d090 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
2d0a0 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
2d0b0 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
2d0c0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
2d0d0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
2d0e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
2d0f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2d100 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2d110 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
2d120 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
2d130 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2d140 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  n the length of 
2d150 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
2d160 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2d170 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
2d180 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
2d190 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ator..** If the 
2d1a0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2d1b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2d1c0 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74  _blob() is negat
2d1d0 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ive, then.** the
2d1e0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2d1f0 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20  efined..** If a 
2d200 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75  non-negative fou
2d210 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
2d220 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c   provided to sql
2d230 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2d240 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
2d250 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20  ind_text16() or 
2d260 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2d270 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68  t64() then.** th
2d280 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  at parameter mus
2d290 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
2d2a0 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68  fset.** where th
2d2b0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
2d2c0 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73   would occur ass
2d2d0 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67  uming the string
2d2e0 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72   were NUL.** ter
2d2f0 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
2d300 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
2d310 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66  occur at byte of
2d320 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20  fsets less than 
2d330 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66  .** the value of
2d340 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2d350 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72  meter then the r
2d360 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
2d370 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f  value will.** co
2d380 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
2d390 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ULs.  The result
2d3a0 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
2d3b0 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67  involving string
2d3c0 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64  s.** with embedd
2d3d0 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
2d3e0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2d3f0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2d400 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20  to the BLOB and 
2d410 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69  string binding i
2d420 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
2d430 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
2d440 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
2d450 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
2d460 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
2d470 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
2d480 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
2d490 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
2d4a0 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
2d4b0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
2d4c0 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
2d4d0 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64  the call to bind
2d4e0 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e   API fails..** ^
2d4f0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
2d500 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
2d510 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
2d520 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
2d530 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
2d540 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
2d550 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
2d560 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
2d570 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
2d580 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
2d590 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74   freed..** ^If t
2d5a0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2d5b0 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
2d5c0 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
2d5d0 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
2d5e0 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
2d5f0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
2d600 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
2d610 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
2d620 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2d630 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
2d640 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
2d650 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
2d660 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2d670 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 62  _text64() must b
2d680 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c  e one of.** [SQL
2d690 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
2d6a0 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49  TE_UTF16], [SQLI
2d6b0 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20  TE_UTF16BE], or 
2d6c0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
2d6d0 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74  .** to specify t
2d6e0 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74  he encoding of t
2d6f0 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 74  he text in the t
2d700 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20  hird parameter. 
2d710 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68   If.** the sixth
2d720 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2d730 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2d740 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
2d750 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20   the.** allowed 
2d760 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f  values shown abo
2d770 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65  ve, or if the te
2d780 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  xt encoding is d
2d790 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d  ifferent.** from
2d7a0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70   the encoding sp
2d7b0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ecified by the s
2d7c0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  ixth parameter, 
2d7d0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2d7e0 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  r.** is undefine
2d7f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2d800 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2d810 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
2d820 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
2d830 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
2d840 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
2d850 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
2d860 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
2d870 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
2d880 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
2d890 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
2d8a0 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
2d8b0 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
2d8c0 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
2d8d0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
2d8e0 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
2d8f0 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
2d900 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
2d910 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
2d920 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
2d930 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
2d940 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
2d950 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
2d960 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
2d970 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
2d980 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
2d990 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
2d9a0 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
2d9b0 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
2d9c0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2d9d0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2d9e0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
2d9f0 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
2da00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2da10 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
2da20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2da30 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
2da40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2da50 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
2da60 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
2da70 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
2da80 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
2da90 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
2daa0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2dab0 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
2dac0 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
2dad0 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
2dae0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2daf0 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
2db00 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
2db10 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
2db20 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
2db30 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
2db40 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
2db50 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
2db60 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
2db70 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
2db80 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
2db90 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
2dba0 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
2dbb0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
2dbc0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
2dbd0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
2dbe0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
2dbf0 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
2dc00 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
2dc10 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
2dc20 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f  ..** ^[SQLITE_TO
2dc30 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72  OBIG] might be r
2dc40 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73  eturned if the s
2dc50 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20  ize of a string 
2dc60 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65  or BLOB.** excee
2dc70 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65  ds limits impose
2dc80 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  d by [sqlite3_li
2dc90 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
2dca0 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a  IT_LENGTH]) or.*
2dcb0 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45  * [SQLITE_MAX_LE
2dcc0 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  NGTH]..** ^[SQLI
2dcd0 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
2dce0 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
2dcf0 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
2dd00 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
2dd10 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
2dd20 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
2dd30 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
2dd40 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2dd50 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2dd60 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2dd70 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2dd80 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2dd90 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
2dda0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2ddb0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2ddc0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2ddd0 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71  QLITE_APICALL sq
2dde0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2ddf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2de00 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2de10 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 53 51 4c   int n, void(SQL
2de20 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 29 28  ITE_CALLBACK *)(
2de30 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
2de40 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41  API int SQLITE_A
2de50 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  PICALL sqlite3_b
2de60 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74  ind_blob64(sqlit
2de70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2de80 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69  onst void*, sqli
2de90 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20  te3_uint64,.    
2dea0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2deb0 20 20 20 20 76 6f 69 64 28 53 51 4c 49 54 45 5f      void(SQLITE_
2dec0 43 41 4c 4c 42 41 43 4b 20 2a 29 28 76 6f 69 64  CALLBACK *)(void
2ded0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
2dee0 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41  int SQLITE_APICA
2def0 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2df00 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2df10 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
2df20 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  e);.SQLITE_API i
2df30 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c  nt SQLITE_APICAL
2df40 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  L sqlite3_bind_i
2df50 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2df60 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c  , int, int);.SQL
2df70 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2df80 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74  TE_APICALL sqlit
2df90 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
2dfa0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2dfb0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
2dfc0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2dfd0 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20   SQLITE_APICALL 
2dfe0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
2dff0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
2e000 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
2e010 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 49  I int SQLITE_API
2e020 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2e030 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
2e040 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  tmt*,int,const c
2e050 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 53 51  har*,int,void(SQ
2e060 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 29  LITE_CALLBACK *)
2e070 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
2e080 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2e090 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  APICALL sqlite3_
2e0a0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
2e0b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2e0c0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2e0d0 2c 20 76 6f 69 64 28 53 51 4c 49 54 45 5f 43 41  , void(SQLITE_CA
2e0e0 4c 4c 42 41 43 4b 20 2a 29 28 76 6f 69 64 2a 29  LLBACK *)(void*)
2e0f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2e100 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c  t SQLITE_APICALL
2e110 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2e120 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt64(sqlite3_stm
2e130 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
2e140 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  har*, sqlite3_ui
2e150 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2e160 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2e170 6f 69 64 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42  oid(SQLITE_CALLB
2e180 41 43 4b 20 2a 29 28 76 6f 69 64 2a 29 2c 20 75  ACK *)(void*), u
2e190 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63  nsigned char enc
2e1a0 6f 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41  oding);.SQLITE_A
2e1b0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50  PI int SQLITE_AP
2e1c0 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  ICALL sqlite3_bi
2e1d0 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
2e1e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2e1f0 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
2e200 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
2e210 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c  nt SQLITE_APICAL
2e220 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  L sqlite3_bind_z
2e230 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
2e240 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
2e250 6e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  n);.SQLITE_API i
2e260 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c  nt SQLITE_APICAL
2e270 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  L sqlite3_bind_z
2e280 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  eroblob64(sqlite
2e290 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
2e2a0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a  lite3_uint64);..
2e2b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e2c0 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
2e2d0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48  rameters.** METH
2e2e0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2e2f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
2e300 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
2e310 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
2e320 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
2e330 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
2e340 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e350 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
2e360 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
2e370 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
2e380 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
2e390 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
2e3a0 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
2e3b0 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
2e3c0 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
2e3d0 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
2e3e0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
2e3f0 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
2e400 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
2e410 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
2e420 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
2e430 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
2e440 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2e450 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
2e460 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
2e470 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
2e480 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
2e490 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
2e4a0 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
2e4b0 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
2e4c0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
2e4d0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2e4e0 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
2e4f0 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
2e500 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
2e510 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
2e520 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2e530 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2e540 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2e550 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2e560 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
2e570 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2e580 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e590 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
2e5a0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2e5b0 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74  TE_APICALL sqlit
2e5c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2e5d0 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
2e5e0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2e5f0 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
2e600 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
2e610 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  r.** METHOD: sql
2e620 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2e630 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2e640 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2e650 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (P,N) interface 
2e660 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2e670 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20  ame of the N-th 
2e680 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
2e690 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
2e6a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
2e6b0 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65  * ^(SQL paramete
2e6c0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
2e6d0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2e6e0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2e6f0 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
2e700 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
2e710 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
2e720 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2e730 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
2e740 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
2e750 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2e760 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
2e770 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
2e780 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
2e790 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
2e7a0 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50  he name.)^.** ^P
2e7b0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2e7c0 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
2e7d0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
2e7e0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
2e7f0 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65  me.** and are re
2e800 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61  ferred to as "na
2e810 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e  meless" or "anon
2e820 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
2e830 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  "..**.** ^The fi
2e840 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
2e850 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
2e860 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
2e870 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
2e880 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
2e890 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74  ge or if the N-t
2e8a0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
2e8b0 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
2e8c0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
2e8d0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  d.  ^The returne
2e8e0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
2e8f0 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
2e900 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
2e910 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
2e920 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
2e930 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
2e940 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
2e950 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2e960 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2e970 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2e980 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2e990 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2e9a0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2e9b0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2e9c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2e9d0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2e9e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2e9f0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2ea00 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2ea10 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
2ea20 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71  QLITE_APICALL sq
2ea30 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2ea40 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
2ea50 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
2ea60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ea70 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
2ea80 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
2ea90 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44  n Name.** METHOD
2eaa0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2eab0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
2eac0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
2ead0 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
2eae0 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
2eaf0 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
2eb00 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
2eb10 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
2eb20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
2eb30 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2eb40 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2eb50 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
2eb60 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
2eb70 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
2eb80 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
2eb90 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
2eba0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
2ebb0 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
2ebc0 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
2ebd0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
2ebe0 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
2ebf0 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
2ec00 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
2ec10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2ec20 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
2ec30 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2ec40 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2ec50 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2ec60 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2ec70 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2ec80 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2ec90 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2eca0 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  _name()]..*/.SQL
2ecb0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2ecc0 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74  TE_APICALL sqlit
2ecd0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2ece0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
2ecf0 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
2ed00 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
2ed10 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2ed20 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
2ed30 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
2ed40 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
2ed50 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2ed60 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
2ed70 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
2ed80 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
2ed90 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
2eda0 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
2edb0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2edc0 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
2edd0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
2ede0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
2edf0 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
2ee00 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
2ee10 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
2ee20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  NULL..*/.SQLITE_
2ee30 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41  API int SQLITE_A
2ee40 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  PICALL sqlite3_c
2ee50 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
2ee60 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2ee70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2ee80 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
2ee90 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2eea0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2eeb0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2eec0 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
2eed0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2eee0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
2eef0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2ef00 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2ef10 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f  ement]. ^This ro
2ef20 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
2ef30 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
2ef40 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
2ef50 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
2ef60 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
2ef70 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
2ef80 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  E])..**.** See a
2ef90 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
2efa0 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53  ta_count()].*/.S
2efb0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2efc0 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c  LITE_APICALL sql
2efd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2efe0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2eff0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2f000 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
2f010 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
2f020 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
2f030 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2f040 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2f050 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
2f060 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
2f070 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
2f080 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
2f090 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
2f0a0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2f0b0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2f0c0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
2f0d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2f0e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2f0f0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2f100 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
2f110 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
2f120 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
2f130 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2f140 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2f150 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
2f160 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
2f170 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2f180 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2f190 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
2f1a0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2f1b0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2f1c0 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
2f1d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2f1e0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
2f1f0 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
2f200 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
2f210 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
2f220 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2f230 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
2f240 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
2f250 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2f260 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
2f270 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
2f280 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2f290 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2f2a0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2f2b0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2f2c0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2f2d0 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2f2e0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2f2f0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2f300 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2f310 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
2f320 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f330 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
2f340 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2f350 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
2f360 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
2f370 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2f380 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
2f390 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
2f3a0 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
2f3b0 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
2f3c0 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
2f3d0 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
2f3e0 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
2f3f0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
2f400 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2f410 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2f420 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
2f430 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2f440 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
2f450 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
2f460 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
2f470 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
2f480 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
2f490 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
2f4a0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2f4b0 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
2f4c0 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
2f4d0 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
2f4e0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
2f4f0 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
2f500 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2f510 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
2f520 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33  _APICALL sqlite3
2f530 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
2f540 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2f550 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  N);.SQLITE_API c
2f560 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
2f570 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65  E_APICALL sqlite
2f580 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2f590 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f5a0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
2f5b0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
2f5c0 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
2f5d0 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48  y Result.** METH
2f5e0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2f5f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2f600 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
2f610 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
2f620 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
2f630 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
2f640 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
2f650 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
2f660 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
2f670 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
2f680 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
2f690 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
2f6a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
2f6b0 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
2f6c0 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
2f6d0 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
2f6e0 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
2f6f0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
2f700 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
2f710 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
2f720 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
2f730 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
2f740 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2f750 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
2f760 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
2f770 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
2f780 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
2f790 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
2f7a0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2f7b0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
2f7c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f7d0 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
2f7e0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
2f7f0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2f800 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
2f810 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
2f820 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
2f830 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
2f840 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
2f850 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
2f860 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
2f870 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
2f880 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
2f890 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
2f8a0 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
2f8b0 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
2f8c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2f8d0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
2f8e0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
2f8f0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
2f900 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2f910 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
2f920 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
2f930 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2f940 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
2f950 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
2f960 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2f970 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
2f980 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
2f990 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
2f9a0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
2f9b0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2f9c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
2f9d0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
2f9e0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
2f9f0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
2fa00 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
2fa10 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
2fa20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
2fa30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
2fa40 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
2fa50 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
2fa60 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
2fa70 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
2fa80 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
2fa90 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
2faa0 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
2fab0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2fac0 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
2fad0 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
2fae0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
2faf0 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
2fb00 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
2fb10 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
2fb20 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
2fb30 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
2fb40 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
2fb50 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
2fb60 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
2fb70 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
2fb80 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
2fb90 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
2fba0 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
2fbb0 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
2fbc0 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
2fbd0 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
2fbe0 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
2fbf0 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
2fc00 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
2fc10 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
2fc20 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
2fc30 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
2fc40 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
2fc50 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
2fc60 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
2fc70 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2fc80 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
2fc90 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
2fca0 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
2fcb0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
2fcc0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
2fcd0 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
2fce0 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
2fcf0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
2fd00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
2fd10 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
2fd20 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2fd30 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
2fd40 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
2fd50 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
2fd60 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
2fd70 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
2fd80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2fd90 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
2fda0 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
2fdb0 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
2fdc0 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
2fdd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2fde0 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
2fdf0 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
2fe00 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
2fe10 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2fe20 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ined..*/.SQLITE_
2fe30 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2fe40 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73  SQLITE_APICALL s
2fe50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2fe60 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
2fe70 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2fe80 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2fe90 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 41 50   void *SQLITE_AP
2fea0 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  ICALL 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 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2fed0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2fee0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2fef0 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73  SQLITE_APICALL s
2ff00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2ff10 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
2ff20 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2ff30 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2ff40 69 64 20 2a 53 51 4c 49 54 45 5f 41 50 49 43 41  id *SQLITE_APICA
2ff50 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
2ff60 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
2ff70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2ff80 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2ff90 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
2ffa0 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33  _APICALL sqlite3
2ffb0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
2ffc0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2ffd0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2ffe0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
2fff0 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71  QLITE_APICALL sq
30000 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
30010 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
30020 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
30030 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30040 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
30050 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
30060 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
30070 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
30080 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
30090 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
300a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
300b0 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
300c0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
300d0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
300e0 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
300f0 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
30100 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
30110 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
30120 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
30130 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
30140 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
30150 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
30160 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
30170 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
30180 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
30190 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
301a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
301b0 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
301c0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
301d0 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
301e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
301f0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
30200 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
30210 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
30220 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
30230 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
30240 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
30250 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
30260 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
30270 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
30280 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
30290 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
302a0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
302b0 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
302c0 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
302d0 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
302e0 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
302f0 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
30300 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
30310 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
30320 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
30330 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
30340 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
30350 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
30360 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
30370 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
30380 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
30390 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
303a0 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
303b0 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
303c0 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
303d0 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
303e0 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
303f0 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
30400 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
30410 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
30420 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
30430 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
30440 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
30450 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
30460 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
30470 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
30480 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
30490 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
304a0 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
304b0 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
304c0 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
304d0 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  es..*/.SQLITE_AP
304e0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
304f0 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c  LITE_APICALL sql
30500 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
30510 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
30520 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
30530 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
30540 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73  SQLITE_APICALL s
30550 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
30560 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
30570 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
30580 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
30590 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
305a0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f  atement.** METHO
305b0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
305c0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
305d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
305e0 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
305f0 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
30600 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
30610 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
30620 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
30630 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
30640 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
30650 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
30660 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
30670 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
30680 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
30690 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
306a0 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
306b0 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
306c0 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
306d0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
306e0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
306f0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
30700 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
30710 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
30720 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
30730 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
30740 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
30750 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
30760 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
30770 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
30780 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
30790 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
307a0 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
307b0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
307c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
307d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
307e0 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
307f0 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
30800 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
30810 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
30820 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
30830 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
30840 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
30850 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
30860 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
30870 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
30880 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
30890 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
308a0 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
308b0 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
308c0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
308d0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
308e0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
308f0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
30900 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
30910 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
30920 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
30930 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
30940 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
30950 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
30960 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
30970 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
30980 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
30990 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
309a0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
309b0 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
309c0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
309d0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
309e0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
309f0 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
30a00 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
30a10 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
30a20 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
30a30 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
30a40 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
30a50 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
30a60 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
30a70 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
30a80 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
30a90 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
30aa0 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
30ab0 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
30ac0 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
30ad0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
30ae0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
30af0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
30b00 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
30b10 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
30b20 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
30b30 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
30b40 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
30b50 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
30b60 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
30b70 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
30b80 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
30b90 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
30ba0 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
30bb0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
30bc0 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
30bd0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
30be0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
30bf0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
30c00 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
30c10 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
30c20 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
30c30 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
30c40 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
30c50 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
30c60 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
30c70 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
30c80 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
30c90 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
30ca0 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
30cb0 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
30cc0 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
30cd0 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
30ce0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
30cf0 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
30d00 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
30d10 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
30d20 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
30d30 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
30d40 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
30d50 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
30d60 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
30d70 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
30d80 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
30d90 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
30da0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
30db0 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
30dc0 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
30dd0 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
30de0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
30df0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
30e00 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
30e10 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
30e20 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
30e30 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
30e40 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
30e50 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
30e60 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
30e70 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
30e80 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
30e90 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
30ea0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
30eb0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
30ec0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
30ed0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
30ee0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
30ef0 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
30f00 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
30f10 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
30f20 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
30f30 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
30f40 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
30f50 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
30f60 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
30f70 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
30f80 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
30f90 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
30fa0 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
30fb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
30fc0 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
30fd0 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
30fe0 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
30ff0 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
31000 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
31010 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
31020 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
31030 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
31040 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
31050 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
31060 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
31070 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
31080 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
31090 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
310a0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
310b0 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
310c0 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
310d0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
310e0 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
310f0 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
31100 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
31110 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
31120 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
31130 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
31140 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
31150 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
31160 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
31170 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
31180 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
31190 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
311a0 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
311b0 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
311c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
311d0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
311e0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
311f0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
31200 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
31210 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
31220 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
31230 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
31240 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
31250 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
31260 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
31270 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
31280 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
31290 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
312a0 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
312b0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
312c0 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
312d0 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
312e0 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
312f0 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
31300 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
31310 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
31320 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
31330 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
31340 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
31350 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
31360 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
31370 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
31380 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
31390 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
313a0 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
313b0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
313c0 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
313d0 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
313e0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
313f0 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
31400 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
31410 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
31420 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
31430 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
31440 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
31450 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
31460 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
31470 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
31480 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
31490 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
314a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
314b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
314c0 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
314d0 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
314e0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
314f0 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
31500 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
31510 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
31520 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
31530 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
31540 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
31550 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
31560 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
31570 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
31580 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
31590 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
315a0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
315b0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
315c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
315d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
315e0 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
315f0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
31600 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
31610 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
31620 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
31630 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
31640 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
31650 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
31660 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
31670 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
31680 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
31690 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
316a0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
316b0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
316c0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
316d0 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41  int SQLITE_APICA
316e0 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  LL sqlite3_step(
316f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
31700 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31710 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   Number of colum
31720 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73  ns in a result s
31730 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
31740 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
31750 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
31760 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65  ta_count(P) inte
31770 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
31780 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
31790 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75  mns in the.** cu
317a0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
317b0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
317c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
317d0 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72  nt] P..** ^If pr
317e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
317f0 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65   P does not have
31800 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74   results ready t
31810 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61  o return.** (via
31820 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73   calls to the [s
31830 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
31840 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t | sqlite3_colu
31850 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e  mn_*()] of.** in
31860 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73  terfaces) then s
31870 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
31880 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a  t(P) returns 0..
31890 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
318a0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
318b0 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72  utine also retur
318c0 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e  ns 0 if P is a N
318d0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ULL pointer..** 
318e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
318f0 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
31900 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
31910 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
31920 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
31930 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
31940 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ed [SQLITE_DONE]
31950 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
31960 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a  data_count(P).**
31970 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e   will return non
31980 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75  -zero if previou
31990 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  s call to [sqlit
319a0 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
319b0 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
319c0 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20  ROW], except in 
319d0 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20  the case of the 
319e0 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e  [PRAGMA incremen
319f0 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77  tal_vacuum].** w
31a00 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72  here it always r
31a10 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63  eturns zero sinc
31a20 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74  e each step of t
31a30 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a  hat multi-step.*
31a40 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73  * pragma returns
31a50 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61   0 columns of da
31a60 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ta..**.** See al
31a70 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
31a80 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
31a90 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
31aa0 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71  QLITE_APICALL sq
31ab0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
31ac0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
31ad0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
31ae0 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
31af0 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
31b00 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
31b10 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
31b20 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
31b30 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
31b40 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
31b50 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
31b60 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
31b70 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
31b80 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
31b90 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
31ba0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
31bb0 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
31bc0 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
31bd0 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
31be0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
31bf0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
31c00 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
31c10 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
31c20 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
31c30 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
31c40 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
31c50 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
31c60 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
31c70 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
31c80 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
31c90 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
31ca0 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
31cb0 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
31cc0 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
31cd0 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
31ce0 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
31cf0 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
31d00 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
31d10 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
31d20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
31d30 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
31d40 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
31d50 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
31d60 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
31d70 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
31d80 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
31d90 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
31da0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
31db0 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
31dc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
31dd0 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
31de0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
31df0 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
31e00 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
31e10 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
31e20 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
31e30 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
31e40 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
31e50 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
31e60 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
31e70 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
31e80 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
31e90 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
31ea0 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
31eb0 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
31ec0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
31ed0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
31ee0 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
31ef0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
31f00 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
31f10 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
31f20 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
31f30 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
31f40 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
31f50 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
31f60 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
31f70 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
31f80 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
31f90 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
31fa0 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
31fb0 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
31fc0 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
31fd0 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
31fe0 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
31ff0 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
32000 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
32010 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
32020 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
32030 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
32040 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
32050 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
32060 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
32070 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
32080 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
32090 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
320a0 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
320b0 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
320c0 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
320d0 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
320e0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
320f0 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
32100 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
32110 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
32120 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
32130 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
32140 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
32150 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
32160 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
32170 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
32180 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
32190 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
321a0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
321b0 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
321c0 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
321d0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
321e0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
321f0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
32200 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
32210 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
32220 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
32230 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
32240 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
32250 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
32260 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
32270 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
32280 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
32290 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
322a0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
322b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
322c0 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
322d0 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
322e0 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
322f0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
32300 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
32310 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
32320 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
32330 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
32340 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
32350 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
32360 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
32370 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
32380 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
32390 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
323a0 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
323b0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
323c0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
323d0 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
323e0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
323f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
32400 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
32410 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
32420 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
32430 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
32440 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
32450 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
32460 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
32470 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
32480 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
32490 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
324a0 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
324b0 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
324c0 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
324d0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
324e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
324f0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
32500 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
32510 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
32520 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
32530 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
32540 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
32550 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
32560 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
32570 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
32580 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
32590 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
325a0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
325b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
325c0 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
325d0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
325e0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
325f0 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
32600 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
32610 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
32620 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
32630 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
32640 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
32650 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
32660 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
32670 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
32680 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
32690 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
326a0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
326b0 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
326c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
326d0 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
326e0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
326f0 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
32700 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
32710 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
32720 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
32730 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
32740 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
32750 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
32760 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
32770 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
32780 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
32790 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
327a0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
327b0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
327c0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
327d0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
327e0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
327f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
32800 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
32810 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
32820 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
32830 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
32840 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
32850 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
32860 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
32870 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
32880 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
32890 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
328a0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
328b0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
328c0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
328d0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
328e0 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
328f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
32900 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
32910 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
32920 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
32930 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
32940 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
32950 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
32960 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
32970 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
32980 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
32990 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
329a0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
329b0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
329c0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
329d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
329e0 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
329f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
32a00 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
32a10 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
32a20 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
32a30 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
32a40 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
32a50 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
32a60 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
32a70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32a80 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
32a90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32aa0 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
32ab0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
32ac0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
32ad0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
32ae0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
32af0 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
32b00 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
32b10 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
32b20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
32b30 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
32b40 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
32b50 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
32b60 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
32b70 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
32b80 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
32b90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
32ba0 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
32bb0 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
32bc0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
32bd0 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e   <b>Warning:</b>
32be0 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
32bf0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
32c00 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
32c10 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
32c20 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
32c30 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
32c40 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64  In a multithread
32c50 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a  ed environment,.
32c60 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  ** an unprotecte
32c70 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
32c80 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20  object may only 
32c90 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77  be used safely w
32ca0 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
32cb0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
32cc0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
32cd0 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
32ce0 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
32cf0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32d00 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
32d10 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
32d20 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
32d30 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
32d40 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
32d50 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
32d60 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
32d70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
32d80 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
32d90 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
32da0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
32db0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
32dc0 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74   behavior is not
32dd0 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a   threadsafe..**.
32de0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
32df0 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
32e00 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
32e10 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
32e20 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  .  ^For.** examp
32e30 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
32e40 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
32e50 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
32e60 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
32e70 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
32e80 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
32e90 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
32ea0 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
32eb0 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
32ec0 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
32ed0 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
32ee0 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
32ef0 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
32f00 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
32f10 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
32f20 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
32f30 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
32f40 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
32f50 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
32f60 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
32f70 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
32f80 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
32f90 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
32fa0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
32fb0 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
32fc0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
32fd0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
32fe0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
32ff0 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
33000 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
33010 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
33020 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
33030 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
33040 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
33050 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
33060 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
33070 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
33080 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
33090 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
330a0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
330b0 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
330c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
330d0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
330e0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
330f0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
33100 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
33110 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
33120 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
33130 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
33140 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
33150 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
33160 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
33170 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
33180 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
33190 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
331a0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
331b0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
331c0 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
331d0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
331e0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
331f0 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a  [CAST] to BLOB.*
33200 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
33210 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
33220 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
33230 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
33240 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
33250 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
33260 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
33270 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  L.** <tr><td>  T
33280 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
33290 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
332a0 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
332b0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
332c0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
332d0 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
332e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
332f0 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
33300 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
33310 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
33320 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
33330 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
33340 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
33350 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
33360 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
33370 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
33380 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
33390 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
333a0 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
333b0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
333c0 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
333d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
333e0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
333f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
33400 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
33410 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
33420 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
33430 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
33440 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
33450 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
33460 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
33470 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
33480 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
33490 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
334a0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
334b0 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
334c0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
334d0 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
334e0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
334f0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
33500 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
33510 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
33520 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
33530 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
33540 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
33550 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
33560 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
33570 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
33580 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
33590 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
335a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
335b0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
335c0 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
335d0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
335e0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
335f0 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
33600 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
33610 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
33620 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
33630 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
33640 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
33650 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
33660 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
33670 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
33680 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
33690 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
336a0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
336b0 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
336c0 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
336d0 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
336e0 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
336f0 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
33700 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
33710 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
33720 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
33730 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
33740 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
33750 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
33760 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
33770 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
33780 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
33790 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
337a0 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
337b0 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
337c0 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
337d0 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
337e0 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
337f0 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
33800 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
33810 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
33820 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
33830 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20  afest policy is 
33840 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
33850 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
33860 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
33870 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
33880 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
33890 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
338a0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
338b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
338c0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
338d0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
338e0 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
338f0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
33900 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
33910 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
33920 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
33930 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
33940 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33950 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
33960 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
33970 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
33980 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
33990 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
339a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
339b0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
339c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
339d0 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
339e0 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
339f0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
33a00 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
33a10 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
33a20 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
33a30 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
33a40 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
33a50 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
33a60 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
33a70 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
33a80 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
33a90 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
33aa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
33ab0 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
33ac0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
33ad0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
33ae0 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
33af0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
33b00 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
33b10 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
33b20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33b30 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
33b40 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
33b50 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
33b60 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
33b70 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
33b80 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
33b90 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
33ba0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
33bb0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
33bc0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
33bd0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
33be0 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
33bf0 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
33c00 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
33c10 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
33c20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
33c30 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e  ically.  Do <em>
33c40 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68  not</em> pass th
33c50 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
33c60 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
33c70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
33c80 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
33c90 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
33ca0 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
33cb0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
33cc0 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
33cd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
33ce0 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
33cf0 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
33d00 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
33d10 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
33d20 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
33d30 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
33d40 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
33d50 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
33d60 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
33d70 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
33d80 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
33d90 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
33da0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
33db0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
33dc0 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
33dd0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
33de0 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  EM].)^.*/.SQLITE
33df0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
33e00 2a 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20  *SQLITE_APICALL 
33e10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33e20 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
33e30 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
33e40 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
33e50 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69  ITE_APICALL sqli
33e60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
33e70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33e80 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
33e90 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
33ea0 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33  _APICALL sqlite3
33eb0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
33ec0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
33ed0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
33ee0 5f 41 50 49 20 64 6f 75 62 6c 65 20 53 51 4c 49  _API double SQLI
33ef0 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74  TE_APICALL sqlit
33f00 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
33f10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33f20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
33f30 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
33f40 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33  _APICALL sqlite3
33f50 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
33f60 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
33f70 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
33f80 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53   sqlite3_int64 S
33f90 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71  QLITE_APICALL sq
33fa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
33fb0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
33fc0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
33fd0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e  ITE_API const un
33fe0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 53 51 4c  signed char *SQL
33ff0 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69  ITE_APICALL sqli
34000 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
34010 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
34020 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
34030 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
34040 2a 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20  *SQLITE_APICALL 
34050 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
34060 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
34070 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
34080 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
34090 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71  QLITE_APICALL sq
340a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
340b0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
340c0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
340d0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76  TE_API sqlite3_v
340e0 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f 41 50 49  alue *SQLITE_API
340f0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
34100 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
34110 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
34120 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
34130 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
34140 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
34150 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54  t Object.** DEST
34160 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f  RUCTOR: sqlite3_
34170 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
34180 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34190 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
341a0 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
341b0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
341c0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
341d0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
341e0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65  valuation of the
341f0 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75   statement encou
34200 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73  ntered no errors
34210 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74  .** or if the st
34220 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72  atement is never
34230 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c   been evaluated,
34240 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69   then sqlite3_fi
34250 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73  nalize() returns
34260 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20  .** SQLITE_OK.  
34270 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
34280 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
34290 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61  f statement S fa
342a0 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  iled, then.** sq
342b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
342c0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70  ) returns the ap
342d0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
342e0 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
342f0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
34300 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e]..**.** ^The s
34310 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
34320 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  S) routine can b
34330 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
34340 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20  point during.** 
34350 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f  the life cycle o
34360 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
34370 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66  ement] S:.** bef
34380 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20  ore statement S 
34390 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65  is ever evaluate
343a0 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20  d, after.** one 
343b0 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f  or more calls to
343c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
343d0 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79  )], or after any
343e0 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c   call.** to [sql
343f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67  ite3_step()] reg
34400 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
34410 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74  er or not the st
34420 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63  atement has.** c
34430 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
34440 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b  on..**.** ^Invok
34450 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ing sqlite3_fina
34460 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c  lize() on a NULL
34470 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
34480 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
34490 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
344a0 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a  ion must finaliz
344b0 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65  e every [prepare
344c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
344d0 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a  order to avoid.*
344e0 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73  * resource leaks
344f0 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76  .  It is a griev
34500 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68  ous error for th
34510 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
34520 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61   try to use.** a
34530 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
34540 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
34550 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
34560 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70    Any use of a p
34570 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
34580 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
34590 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
345a0 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75   can result in u
345b0 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20  ndefined and.** 
345c0 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
345d0 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67  vior such as seg
345e0 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20  faults and heap 
345f0 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53  corruption..*/.S
34600 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
34610 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c  LITE_APICALL sql
34620 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
34630 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
34640 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
34650 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
34660 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
34670 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44  Object.** METHOD
34680 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
34690 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
346a0 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
346b0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
346c0 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
346d0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
346e0 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
346f0 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
34700 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
34710 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
34720 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
34730 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
34740 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
34750 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
34760 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
34770 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
34780 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
34790 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
347a0 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
347b0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
347c0 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
347d0 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
347e0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
347f0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
34800 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
34810 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
34820 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
34830 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
34840 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
34850 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
34860 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
34870 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
34880 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
34890 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
348a0 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
348b0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
348c0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
348d0 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
348e0 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
348f0 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
34900 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
34910 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
34920 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
34930 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
34940 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
34950 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
34960 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
34970 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
34980 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
34990 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
349a0 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
349b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
349c0 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
349d0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
349e0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
349f0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
34a00 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
34a10 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
34a20 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
34a30 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
34a40 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
34a50 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
34a60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
34a70 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
34a80 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c  t SQLITE_APICALL
34a90 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
34aa0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
34ab0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
34ac0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
34ad0 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
34ae0 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
34af0 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
34b00 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
34b10 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
34b20 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34b30 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
34b40 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
34b50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34b60 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
34b70 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
34b80 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
34b90 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
34ba0 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
34bb0 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
34bc0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
34bd0 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
34be0 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
34bf0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
34c00 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
34c10 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
34c20 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
34c30 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
34c40 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
34c50 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
34c60 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
34c70 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
34c80 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
34c90 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
34ca0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
34cb0 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
34cc0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
34cd0 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
34ce0 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
34cf0 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
34d00 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
34d10 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
34d20 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
34d30 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
34d40 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
34d50 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
34d60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
34d70 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
34d80 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
34d90 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
34da0 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
34db0 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
34dc0 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
34dd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
34de0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34df0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
34e00 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
34e10 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
34e20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
34e30 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
34e40 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
34e50 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
34e60 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
34e70 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
34e80 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
34e90 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
34ea0 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
34eb0 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
34ec0 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
34ed0 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
34ee0 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
34ef0 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
34f00 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
34f10 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
34f20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
34f30 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
34f40 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
34f50 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
34f60 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
34f70 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
34f80 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
34f90 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
34fa0 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
34fb0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
34fc0 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
34fd0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
34fe0 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
34ff0 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
35000 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
35010 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
35020 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
35030 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
35040 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
35050 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
35060 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
35070 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
35080 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
35090 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
350a0 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
350b0 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
350c0 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
350d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
350e0 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
350f0 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
35100 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
35110 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
35120 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
35130 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
35140 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
35150 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
35160 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
35170 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
35180 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
35190 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
351a0 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
351b0 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
351c0 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
351d0 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63  ers.  The applic
351e0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74  ation should set
351f0 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
35200 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  to.** [SQLITE_UT
35210 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75  F16LE] if the fu
35220 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
35230 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a  ation invokes .*
35240 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
35250 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20  _text16le()] on 
35260 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51  an input, or [SQ
35270 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66  LITE_UTF16BE] if
35280 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
35290 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b  tation invokes [
352a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
352b0 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16be()] on an 
352c0 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51  input, or.** [SQ
352d0 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b  LITE_UTF16] if [
352e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
352f0 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  xt16()] is used,
35300 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   or [SQLITE_UTF8
35310 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20  ].** otherwise. 
35320 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66   ^The same SQL f
35330 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
35340 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70  egistered multip
35350 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a  le times using.*
35360 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66  * different pref
35370 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
35380 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65  ings, with diffe
35390 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
353a0 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ions for.** each
353b0 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57   encoding..** ^W
353c0 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
353d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
353e0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
353f0 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
35400 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
35410 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
35420 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
35430 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
35440 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
35450 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
35460 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  h parameter may 
35470 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52  optionally be OR
35480 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
35490 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a  DETERMINISTIC].*
354a0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74  * to signal that
354b0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69   the function wi
354c0 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
354d0 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74   the same result
354e0 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61   given.** the sa
354f0 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e  me inputs within
35500 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
35510 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53  atement.  Most S
35520 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  QL functions are
35530 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69  .** deterministi
35540 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e  c.  The built-in
35550 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20   [random()] SQL 
35560 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65  function is an e
35570 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66  xample of a.** f
35580 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  unction that is 
35590 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69  not deterministi
355a0 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71  c.  The SQLite q
355b0 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20  uery planner is 
355c0 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f  able to.** perfo
355d0 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70  rm additional op
355e0 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64  timizations on d
355f0 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e  eterministic fun
35600 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a  ctions, so use.*
35610 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
35620 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20  _DETERMINISTIC] 
35630 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e  flag is recommen
35640 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62  ded where possib
35650 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  le..**.** ^(The 
35660 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
35670 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
35680 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
35690 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
356a0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
356b0 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
356c0 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
356d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
356e0 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
356f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
35700 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
35710 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
35720 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
35730 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
35740 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
35750 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
35760 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
35770 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
35780 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
35790 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
357a0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
357b0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
357c0 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
357d0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
357e0 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
357f0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
35800 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
35810 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
35820 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
35830 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
35840 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
35850 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
35860 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
35870 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
35880 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
35890 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
358a0 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
358b0 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
358c0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
358d0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
358e0 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
358f0 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
35900 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
35910 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
35920 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
35930 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
35940 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
35950 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
35960 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
35970 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
35980 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
35990 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
359a0 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
359b0 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
359c0 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
359d0 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
359e0 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
359f0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
35a00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
35a10 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
35a20 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
35a30 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
35a40 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
35a50 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35a60 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
35a70 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
35a80 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
35a90 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
35aa0 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
35ab0 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
35ac0 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
35ad0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
35ae0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
35af0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
35b00 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
35b10 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
35b20 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
35b30 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35b40 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
35b50 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
35b60 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
35b70 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
35b80 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
35b90 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
35ba0 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
35bb0 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
35bc0 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
35bd0 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
35be0 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
35bf0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
35c00 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
35c10 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
35c20 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
35c30 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
35c40 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
35c50 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
35c60 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
35c70 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
35c80 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
35c90 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
35ca0 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
35cb0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
35cc0 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
35cd0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
35ce0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
35cf0 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
35d00 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
35d10 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
35d20 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
35d30 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
35d40 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
35d50 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
35d60 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
35d70 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
35d80 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
35d90 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
35da0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
35db0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
35dc0 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
35dd0 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
35de0 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
35df0 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
35e00 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
35e10 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
35e20 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
35e30 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
35e40 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
35e50 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
35e60 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
35e70 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
35e80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35e90 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
35ea0 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
35eb0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
35ec0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
35ed0 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
35ee0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
35ef0 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
35f00 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
35f10 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
35f20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35f30 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
35f40 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
35f50 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
35f60 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
35f70 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
35f80 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
35f90 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41  API int SQLITE_A
35fa0 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  PICALL sqlite3_c
35fb0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
35fc0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
35fd0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
35fe0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
35ff0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
36000 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
36010 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 53 51  pApp,.  void (SQ
36020 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78  LITE_CALLBACK *x
36030 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
36040 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
36050 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
36060 6f 69 64 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c  oid (SQLITE_CALL
36070 42 41 43 4b 20 2a 78 53 74 65 70 29 28 73 71 6c  BACK *xStep)(sql
36080 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
36090 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
360a0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 53 51 4c 49  *),.  void (SQLI
360b0 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 46 69  TE_CALLBACK *xFi
360c0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
360d0 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  text*).);.SQLITE
360e0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
360f0 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  APICALL sqlite3_
36100 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
36110 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
36120 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
36130 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
36140 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
36150 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
36160 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
36170 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b  (SQLITE_CALLBACK
36180 20 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33   *xFunc)(sqlite3
36190 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
361a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
361b0 20 20 76 6f 69 64 20 28 53 51 4c 49 54 45 5f 43    void (SQLITE_C
361c0 41 4c 4c 42 41 43 4b 20 2a 78 53 74 65 70 29 28  ALLBACK *xStep)(
361d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
361e0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
361f0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 53  ue**),.  void (S
36200 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a  QLITE_CALLBACK *
36210 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
36220 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c  context*).);.SQL
36230 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
36240 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74  TE_APICALL sqlit
36250 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
36260 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
36270 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
36280 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
36290 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
362a0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
362b0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
362c0 6f 69 64 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c  oid (SQLITE_CALL
362d0 42 41 43 4b 20 2a 78 46 75 6e 63 29 28 73 71 6c  BACK *xFunc)(sql
362e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
362f0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
36300 2a 29 2c 0a 20 20 76 6f 69 64 20 28 53 51 4c 49  *),.  void (SQLI
36310 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 53 74  TE_CALLBACK *xSt
36320 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
36330 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
36340 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
36350 64 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  d (SQLITE_CALLBA
36360 43 4b 20 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  CK *xFinal)(sqli
36370 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
36380 20 76 6f 69 64 28 53 51 4c 49 54 45 5f 43 41 4c   void(SQLITE_CAL
36390 4c 42 41 43 4b 20 2a 78 44 65 73 74 72 6f 79 29  LBACK *xDestroy)
363a0 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
363b0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
363c0 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
363d0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
363e0 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
363f0 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
36400 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
36410 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
36420 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
36430 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
36440 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
36450 20 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20          1    /* 
36460 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35  IMP: R-37514-355
36470 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  66 */.#define SQ
36480 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
36490 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a      2    /* IMP:
364a0 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a   R-03371-37637 *
364b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
364c0 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
364d0 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35  3    /* IMP: R-5
364e0 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64  1971-34154 */.#d
364f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
36500 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
36510 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
36520 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
36530 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
36540 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
36550 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f  /* Deprecated */
36560 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36570 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
36580 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
36590 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
365a0 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
365b0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
365c0 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68  n Flags.**.** Th
365d0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  ese constants ma
365e0 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68  y be ORed togeth
365f0 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  er with the .** 
36600 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70  [SQLITE_UTF8 | p
36610 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
36620 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66  coding] as the f
36630 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
36640 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
36650 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
36660 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
36670 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c  e_function16()],
36680 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
36690 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
366a0 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  v2()]..*/.#defin
366b0 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49  e SQLITE_DETERMI
366c0 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a  NISTIC    0x800.
366d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
366e0 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
366f0 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
36700 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
36710 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
36720 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
36730 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
36740 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
36750 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
36760 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
36770 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
36780 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
36790 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
367a0 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
367b0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
367c0 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
367d0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
367e0 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65  s.  To encourage
367f0 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20   programmers to 
36800 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66  avoid.** these f
36810 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c  unctions, we wil
36820 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68  l not explain wh
36830 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
36840 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
36850 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
36860 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
36870 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53  DEPRECATED int S
36880 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71  QLITE_APICALL sq
36890 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
368a0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
368b0 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
368c0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
368d0 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45  CATED int SQLITE
368e0 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33  _APICALL sqlite3
368f0 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
36900 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
36910 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
36920 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45  CATED int SQLITE
36930 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33  _APICALL sqlite3
36940 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
36950 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
36960 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
36970 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
36980 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
36990 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c  nt SQLITE_APICAL
369a0 4c 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  L sqlite3_global
369b0 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
369c0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
369d0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
369e0 64 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c  d SQLITE_APICALL
369f0 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
36a00 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
36a10 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
36a20 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
36a30 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73  SQLITE_APICALL s
36a40 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
36a50 61 72 6d 28 76 6f 69 64 28 53 51 4c 49 54 45 5f  arm(void(SQLITE_
36a60 43 41 4c 4c 42 41 43 4b 20 2a 29 28 76 6f 69 64  CALLBACK *)(void
36a70 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  *,sqlite3_int64,
36a80 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20  int),.          
36a90 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
36aa0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
36ab0 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
36ac0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
36ad0 69 6e 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a  ing SQL Values.*
36ae0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
36af0 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68  3_value.**.** Th
36b00 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
36b10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
36b20 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
36b30 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
36b40 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
36b50 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
36b60 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
36b70 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
36b80 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
36b90 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
36ba0 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  e.  .**.** The x
36bb0 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
36bc0 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
36bd0 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
36be0 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
36bf0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
36c00 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
36c10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
36c20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
36c30 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
36c40 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
36c50 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
36c60 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
36c70 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
36c80 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
36c90 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
36ca0 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
36cb0 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
36cc0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
36cd0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36ce0 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
36cf0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
36d00 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
36d10 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
36d20 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
36d30 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
36d40 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
36d50 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
36d60 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
36d70 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36d80 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
36d90 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
36da0 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
36db0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
36dc0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
36dd0 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
36de0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
36df0 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
36e00 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
36e10 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
36e20 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
36e30 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
36e40 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
36e50 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
36e60 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
36e70 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
36e80 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
36e90 63 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20  cept that these 
36ea0 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
36eb0 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
36ec0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
36ed0 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
36ee0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
36ef0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
36f00 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
36f10 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
36f20 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
36f30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
36f40 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
36f50 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
36f60 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
36f70 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
36f80 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
36f90 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68  st machine.  ^Th
36fa0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
36fb0 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
36fc0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
36fd0 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
36fe0 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
36ff0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
37000 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
37010 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
37020 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
37030 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
37040 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
37050 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
37060 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
37070 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
37080 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
37090 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
370a0 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
370b0 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
370c0 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
370d0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
370e0 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
370f0 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
37100 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
37110 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
37120 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
37130 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
37140 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
37150 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
37160 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
37170 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
37180 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
37190 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
371a0 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
371b0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
371c0 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
371d0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
371e0 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
371f0 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
37200 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  )^.**.** Please 
37210 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
37220 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
37230 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
37240 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
37250 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
37260 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
37270 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37280 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
37290 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
372a0 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
372b0 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
372c0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
372d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
372e0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
372f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
37300 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
37310 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
37320 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
37330 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
37340 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
37350 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
37360 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
37370 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
37380 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
37390 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
373a0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
373b0 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
373c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
373d0 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
373e0 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  APICALL sqlite3_
373f0 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
37400 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
37410 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
37420 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65  E_APICALL sqlite
37430 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71  3_value_bytes(sq
37440 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
37450 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
37460 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c  LITE_APICALL sql
37470 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
37480 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
37490 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64  *);.SQLITE_API d
374a0 6f 75 62 6c 65 20 53 51 4c 49 54 45 5f 41 50 49  ouble SQLITE_API
374b0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  CALL sqlite3_val
374c0 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
374d0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
374e0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
374f0 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33  _APICALL sqlite3
37500 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
37510 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
37520 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
37530 6e 74 36 34 20 53 51 4c 49 54 45 5f 41 50 49 43  nt64 SQLITE_APIC
37540 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
37550 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
37560 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
37570 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e  API const unsign
37580 65 64 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  ed char *SQLITE_
37590 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  APICALL sqlite3_
375a0 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
375b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
375c0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
375d0 64 20 2a 53 51 4c 49 54 45 5f 41 50 49 43 41 4c  d *SQLITE_APICAL
375e0 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
375f0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
37600 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
37610 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
37620 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71  QLITE_APICALL sq
37630 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
37640 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
37650 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
37660 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c   const void *SQL
37670 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69  ITE_APICALL sqli
37680 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
37690 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  be(sqlite3_value
376a0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
376b0 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c  nt SQLITE_APICAL
376c0 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
376d0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
376e0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
376f0 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43   int SQLITE_APIC
37700 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
37710 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
37720 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37730 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37740 20 46 69 6e 64 69 6e 67 20 54 68 65 20 53 75 62   Finding The Sub
37750 74 79 70 65 20 4f 66 20 53 51 4c 20 56 61 6c 75  type Of SQL Valu
37760 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
37770 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a  lite3_value.**.*
37780 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
37790 6c 75 65 5f 73 75 62 74 79 70 65 28 56 29 20 66  lue_subtype(V) f
377a0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
377b0 74 68 65 20 73 75 62 74 79 70 65 20 66 6f 72 0a  the subtype for.
377c0 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69  ** an [applicati
377d0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
377e0 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e  unction] argumen
377f0 74 20 56 2e 20 20 54 68 65 20 73 75 62 74 79 70  t V.  The subtyp
37800 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
37810 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
37820 70 61 73 73 20 61 20 6c 69 6d 69 74 65 64 20 61  pass a limited a
37830 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74  mount of context
37840 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c   from.** one SQL
37850 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f   function to ano
37860 74 68 65 72 2e 20 20 55 73 65 20 74 68 65 20 5b  ther.  Use the [
37870 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73  sqlite3_result_s
37880 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75  ubtype()].** rou
37890 74 69 6e 65 20 74 6f 20 73 65 74 20 74 68 65 20  tine to set the 
378a0 73 75 62 74 79 70 65 20 66 6f 72 20 74 68 65 20  subtype for the 
378b0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
378c0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  an SQL function.
378d0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  .**.** SQLite ma
378e0 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66 20 73 75  kes no use of su
378f0 62 74 79 70 65 20 69 74 73 65 6c 66 2e 20 20 49  btype itself.  I
37900 74 20 6d 65 72 65 6c 79 20 70 61 73 73 65 73 20  t merely passes 
37910 74 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 66  the subtype.** f
37920 72 6f 6d 20 74 68 65 20 72 65 73 75 6c 74 20 6f  rom the result o
37930 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74 69  f one [applicati
37940 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
37950 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68  unction] into th
37960 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e  e.** input of an
37970 6f 74 68 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45  other..*/.SQLITE
37980 5f 41 50 49 20 75 6e 73 69 67 6e 65 64 20 69 6e  _API unsigned in
37990 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c  t SQLITE_APICALL
379a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73   sqlite3_value_s
379b0 75 62 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  ubtype(sqlite3_v
379c0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
379d0 41 50 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e  API3REF: Copy An
379e0 64 20 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65  d Free SQL Value
379f0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
37a00 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a  ite3_value.**.**
37a10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
37a20 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72  lue_dup(V) inter
37a30 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
37a40 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
37a50 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
37a60 63 74 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73  ct D and returns
37a70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
37a80 61 74 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b  at copy.  ^The [
37a90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72  sqlite3_value] r
37aa0 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20  eturned.** is a 
37ab0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
37ac0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
37ad0 20 65 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70   even if the inp
37ae0 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54  ut is not..** ^T
37af0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
37b00 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63  _dup(V) interfac
37b10 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69  e returns NULL i
37b20 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69  f V is NULL or i
37b30 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
37b40 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a  location fails..
37b50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37b60 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29  e3_value_free(V)
37b70 20 69 6e 74 65 72 66 61 63 65 20 66 72 65 65 73   interface frees
37b80 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   an [sqlite3_val
37b90 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72  ue] object.** pr
37ba0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
37bb0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
37bc0 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e  value_dup()].  ^
37bd0 49 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70  If V is a NULL p
37be0 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73  ointer.** then s
37bf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65  qlite3_value_fre
37c00 65 28 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65  e(V) is a harmle
37c10 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c  ss no-op..*/.SQL
37c20 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
37c30 76 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f 41 50  value *SQLITE_AP
37c40 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  ICALL sqlite3_va
37c50 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71  lue_dup(const sq
37c60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
37c70 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53  QLITE_API void S
37c80 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71  QLITE_APICALL sq
37c90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65  lite3_value_free
37ca0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
37cb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37cc0 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
37cd0 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
37ce0 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  text.** METHOD: 
37cf0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
37d00 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61  **.** Implementa
37d10 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61  tions of aggrega
37d20 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
37d30 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75   use this.** rou
37d40 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
37d50 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72   memory for stor
37d60 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
37d70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
37d80 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
37d90 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
37da0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
37db0 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20  e is called .** 
37dc0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
37dd0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
37de0 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ion, SQLite.** a
37df0 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65  llocates N of me
37e00 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
37e10 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
37e20 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
37e30 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65  ter.** to the ne
37e40 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65  w memory. ^On se
37e50 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
37e60 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
37e70 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
37e80 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
37e90 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
37ea0 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
37eb0 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ance,.** the sam
37ec0 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
37ed0 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61  rned.  Sqlite3_a
37ee0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
37ef0 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a  () is normally.*
37f00 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f  * called once fo
37f10 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  r each invocatio
37f20 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63  n of the xStep c
37f30 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e  allback and then
37f40 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d   one.** last tim
37f50 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61  e when the xFina
37f60 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  l callback is in
37f70 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e  voked.  ^(When n
37f80 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20  o rows match.** 
37f90 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
37fa0 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20  ry, the xStep() 
37fb0 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
37fc0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
37fd0 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  on.** implementa
37fe0 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61  tion is never ca
37ff0 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28  lled and xFinal(
38000 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63  ) is called exac
38010 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20  tly once..** In 
38020 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c  those cases, sql
38030 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
38040 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62  ontext() might b
38050 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  e called for the
38060 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66  .** first time f
38070 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61  rom within xFina
38080 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  l().)^.**.** ^Th
38090 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
380a0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
380b0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
380c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
380d0 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63  .** when first c
380e0 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65  alled if N is le
380f0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
38100 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
38110 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
38120 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
38130 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
38140 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
38150 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
38160 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
38170 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
38180 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
38190 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
381a0 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
381b0 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
381c0 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
381d0 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
381e0 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
381f0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
38200 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
38210 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
38220 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
38230 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
38240 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
38250 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
38260 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69    Within the xFi
38270 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74  nal callback, it
38280 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f   is customary to
38290 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63   set.** N=0 in c
382a0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
382b0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
382c0 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e  t(C,N) so that n
382d0 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20  o .** pointless 
382e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
382f0 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20  ns occur..**.** 
38300 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69  ^SQLite automati
38310 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
38320 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
38330 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
38340 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
38350 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67  t() when the agg
38360 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e  regate query con
38370 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
38380 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
38390 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79  r must be a copy
383a0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
383b0 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
383c0 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
383d0 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
383e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a  first parameter.
383f0 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20  ** to the xStep 
38400 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
38410 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
38420 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
38430 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63  ggregate.** func
38440 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
38450 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
38460 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
38470 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
38480 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
38490 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
384a0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
384b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
384c0 69 64 20 2a 53 51 4c 49 54 45 5f 41 50 49 43 41  id *SQLITE_APICA
384d0 4c 4c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  LL sqlite3_aggre
384e0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
384f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
38500 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
38510 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
38520 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
38530 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
38540 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
38550 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
38560 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
38570 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
38580 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
38590 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
385a0 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
385b0 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
385c0 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
385d0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
385e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
385f0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
38600 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
38610 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
38620 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
38630 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
38640 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
38650 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
38660 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
38670 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
38680 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
38690 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
386a0 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
386b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
386c0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
386d0 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
386e0 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 41 50   void *SQLITE_AP
386f0 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 73  ICALL sqlite3_us
38700 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
38710 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
38720 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
38730 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
38740 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
38750 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
38760 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e  _context.**.** ^
38770 54 68