System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact a482786576d8b0c4fc9ffcf45653845c4a197601:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65  LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 5b 76 65 72 73 69 6f  ** Since [versio
0f00: 6e 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65  n 3.6.18] ([date
0f10: 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a  of:3.6.18]), .**
0f20: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
0f30: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
0f40: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
0f50: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
0f60: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
0f70: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
0f80: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0f90: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
0fa0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
0fb0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
0fc0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
0fd0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
0fe0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
0ff0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
1000: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
1010: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
1020: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
1030: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
1040: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
1050: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
1060: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
1070: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
1080: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 20  -in (UTC) and a 
1090: 53 48 41 31 0a 2a 2a 20 6f 72 20 53 48 41 33 2d  SHA1.** or SHA3-
10a0: 32 35 36 20 68 61 73 68 20 6f 66 20 74 68 65 20  256 hash of the 
10b0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
10c0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
10d0: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
10e0: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
10f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1100: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1110: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1120: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1130: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1140: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1150: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1160: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
1170: 20 20 20 20 20 22 33 2e 31 39 2e 30 22 0a 23 64       "3.19.0".#d
1180: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52  efine SQLITE_VER
1190: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 31 39  SION_NUMBER 3019
11a0: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
11b0: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20  TE_SOURCE_ID    
11c0: 20 20 22 32 30 31 37 2d 30 35 2d 31 30 20 31 36    "2017-05-10 16
11d0: 3a 33 33 3a 34 38 20 39 32 63 35 65 61 37 30 34  :33:48 92c5ea704
11e0: 37 33 32 33 64 31 30 66 37 36 32 38 37 37 63 35  7323d10f762877c5
11f0: 66 35 36 64 32 30 61 33 65 36 30 39 65 38 62 35  f56d20a3e609e8b5
1200: 35 65 66 63 66 65 34 38 38 30 65 66 33 30 34 38  5efcfe4880ef3048
1210: 38 32 31 61 63 31 66 22 0a 0a 2f 2a 0a 2a 2a 20  821ac1f"../*.** 
1220: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
1230: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69  me Library Versi
1240: 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45  on Numbers.** KE
1250: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
1260: 76 65 72 73 69 6f 6e 20 73 71 6c 69 74 65 33 5f  version sqlite3_
1270: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
1280: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
1290: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
12a0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
12b0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
12c0: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
12d0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
12e0: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
12f0: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1300: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1310: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1320: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1330: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1340: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1350: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
1360: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
1370: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
1380: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
1390: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
13a0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
13b0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
13c0: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
13d0: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
13e0: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
13f0: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1400: 20 74 68 75 73 20 65 6e 73 75 72 65 20 74 68 61   thus ensure tha
1410: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1420: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1430: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1440: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1450: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
1460: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1470: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
1480: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
1490: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
14a0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
14b0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
14c0: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
14d0: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
14e0: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
14f0: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1500: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1510: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1520: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1530: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1540: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1550: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
1560: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1570: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
1580: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
1590: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
15a0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
15b0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
15c0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
15d0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
15e0: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
15f0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1600: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1610: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1620: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1630: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1640: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1650: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
1660: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
1670: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
1680: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
1690: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
16a0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
16b0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16c0: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
16d0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
16e0: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
16f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1700: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1710: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1720: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1730: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1740: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1750: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
1760: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
1770: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
1780: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
1790: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
17a0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
17b0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
17c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
17d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
17e0: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
17f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63   SQLITE_EXTERN c
1800: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65  onst char sqlite
1810: 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53 51 4c  3_version[];.SQL
1820: 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
1830: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
1840: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51  ersion(void);.SQ
1850: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
1860: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75  har *sqlite3_sou
1870: 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c  rceid(void);.SQL
1880: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1890: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
18a0: 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a  umber(void);../*
18b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
18c0: 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43  n-Time Library C
18d0: 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f  ompilation Optio
18e0: 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a  ns Diagnostics.*
18f0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1900: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1910: 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20  used() function 
1920: 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a  returns 0 or 1 .
1930: 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68  ** indicating wh
1940: 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66  ether the specif
1950: 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64  ied option was d
1960: 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f  efined at .** co
1970: 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68  mpile time.  ^Th
1980: 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78  e SQLITE_ prefix
1990: 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20   may be omitted 
19a0: 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74  from the .** opt
19b0: 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20  ion name passed 
19c0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  to sqlite3_compi
19d0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e  leoption_used().
19e0: 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71    .**.** ^The sq
19f0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1a00: 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69  ion_get() functi
1a10: 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74  on allows iterat
1a20: 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  ing.** over the 
1a30: 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20  list of options 
1a40: 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65  that were define
1a50: 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  d at compile tim
1a60: 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e  e by.** returnin
1a70: 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69  g the N-th compi
1a80: 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73  le time option s
1a90: 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73  tring.  ^If N is
1aa0: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a   out of range,.*
1ab0: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  * sqlite3_compil
1ac0: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65  eoption_get() re
1ad0: 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1ae0: 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49  nter.  ^The SQLI
1af0: 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69  TE_ .** prefix i
1b00: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61  s omitted from a
1b10: 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  ny strings retur
1b20: 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ned by .** sqlit
1b30: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1b40: 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53  _get()..**.** ^S
1b50: 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64  upport for the d
1b60: 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69  iagnostic functi
1b70: 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ons sqlite3_comp
1b80: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1b90: 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
1ba0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1bb0: 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  t() may be omitt
1bc0: 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67  ed by specifying
1bd0: 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
1be0: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54  _OMIT_COMPILEOPT
1bf0: 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f  ION_DIAGS] optio
1c00: 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  n at compile tim
1c10: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
1c20: 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  o: SQL functions
1c30: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1c40: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61  option_used()] a
1c50: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f  nd.** [sqlite_co
1c60: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1c70: 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70  )] and the [comp
1c80: 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67  ile_options prag
1c90: 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ma]..*/.#ifndef 
1ca0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1cb0: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a  ILEOPTION_DIAGS.
1cc0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1cd0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1ce0: 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20  tion_used(const 
1cf0: 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b  char *zOptName);
1d00: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
1d10: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1d20: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1d30: 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66  t(int N);.#endif
1d40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d50: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1d60: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1d70: 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a  Threadsafe.**.**
1d80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68   ^The sqlite3_th
1d90: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
1da0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ion returns zero
1db0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
1dc0: 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f  ** SQLite was co
1dd0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65  mpiled with mute
1de0: 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65  xing code omitte
1df0: 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20  d due to the.** 
1e00: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1e10: 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  FE] compile-time
1e20: 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65   option being se
1e30: 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51  t to 0..**.** SQ
1e40: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70  Lite can be comp
1e50: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74  iled with or wit
1e60: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57  hout mutexes.  W
1e70: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  hen.** the [SQLI
1e80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43  TE_THREADSAFE] C
1e90: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1ea0: 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d  cro is 1 or 2, m
1eb0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1ec0: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1ed0: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1ee0: 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51   When the.** [SQ
1ef0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1f00: 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a   macro is 0, .**
1f10: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65   the mutexes are
1f20: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f   omitted.  Witho
1f30: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20  ut the mutexes, 
1f40: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a  it is not safe.*
1f50: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20  * to use SQLite 
1f60: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f  concurrently fro
1f70: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  m more than one 
1f80: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e  thread..**.** En
1f90: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69  abling mutexes i
1fa0: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62  ncurs a measurab
1fb0: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70  le performance p
1fc0: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66  enalty..** So if
1fd0: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d   speed is of utm
1fe0: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20  ost importance, 
1ff0: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74  it makes sense t
2000: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  o disable.** the
2010: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66   mutexes.  But f
2020: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74  or maximum safet
2030: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  y, mutexes shoul
2040: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  d be enabled..**
2050: 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65   ^The default be
2060: 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75  havior is for mu
2070: 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62  texes to be enab
2080: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  led..**.** This 
2090: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
20a0: 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c   used by an appl
20b0: 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20  ication to make 
20c0: 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
20d0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
20e0: 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69  te that it is li
20f0: 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61  nking against wa
2100: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
2110: 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73  ** the desired s
2120: 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53  etting of the [S
2130: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
2140: 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54  ] macro..**.** T
2150: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  his interface on
2160: 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68  ly reports on th
2170: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  e compile-time m
2180: 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20  utex setting.** 
2190: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
21a0: 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e  HREADSAFE] flag.
21b0: 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
21e0: 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d  E=1 or =2 then m
21f0: 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c  utexes are enabl
2200: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75  ed by default bu
2210: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c  t.** can be full
2220: 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64  y or partially d
2230: 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
2240: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2250: 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69  _config()].** wi
2260: 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51  th the verbs [SQ
2270: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2280: 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49  LETHREAD], [SQLI
2290: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
22a0: 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  HREAD],.** or [S
22b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
22c0: 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65  IALIZED].  ^(The
22d0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
22e0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
22f0: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
2300: 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79  ction shows only
2310: 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
2320: 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20  e setting of.** 
2330: 74 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e  thread safety, n
2340: 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20  ot any run-time 
2350: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20  changes to that 
2360: 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a  setting made by.
2370: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  ** sqlite3_confi
2380: 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  g(). In other wo
2390: 72 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20  rds, the return 
23a0: 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
23b0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a  e3_threadsafe().
23c0: 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20  ** is unchanged 
23d0: 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  by calls to sqli
23e0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a  te3_config().)^.
23f0: 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74  **.** See the [t
2400: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64  hreading mode] d
2410: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
2420: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2430: 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49  rmation..*/.SQLI
2440: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2450: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f  e3_threadsafe(vo
2460: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
2470: 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
2480: 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65  onnection Handle
2490: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
24a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24b0: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
24c0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
24d0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
24e0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
24f0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
2500: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
2510: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
2520: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
2530: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
2540: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
2550: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
2560: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
2570: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
2580: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
2590: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
25a0: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
25b0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
25c0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
25d0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
25e0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
25f0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
2600: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2610: 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73  se_v2()] are its
2620: 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54   destructors.  T
2630: 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74  here are many ot
2640: 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  her.** interface
2650: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
2660: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2670: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
2680: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2690: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
26a0: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
26b0: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
26c0: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
26d0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
26e0: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
26f0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2700: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
2710: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
2720: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2730: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2740: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2750: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2760: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
2770: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
2780: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
2790: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
27a0: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
27b0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
27c0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
27d0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
27e0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
27f0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
2800: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
2810: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
2820: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2830: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2840: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2850: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2860: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
2870: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
2880: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
2890: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
28a0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28b0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
28c0: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
28d0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
28e0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
28f0: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
2900: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
2910: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2920: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2930: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2940: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2950: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2960: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2970: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
2980: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
2990: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
29a0: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
29b0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
29c0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
29d0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
29e0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
29f0: 23 20 69 66 64 65 66 20 53 51 4c 49 54 45 5f 55  # ifdef SQLITE_U
2a00: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20 20 74  INT64_TYPE.    t
2a10: 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 55 49  ypedef SQLITE_UI
2a20: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
2a30: 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73 65 20  _uint64;.# else 
2a40: 20 0a 20 20 20 20 74 79 70 65 64 65 66 20 75 6e   .    typedef un
2a50: 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e  signed SQLITE_IN
2a60: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
2a70: 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69 66 0a  uint64;.# endif.
2a80: 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d  #elif defined(_M
2a90: 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e  SC_VER) || defin
2aa0: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
2ab0: 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74  .  typedef __int
2ac0: 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  64 sqlite_int64;
2ad0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
2ae0: 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  ned __int64 sqli
2af0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65  te_uint64;.#else
2b00: 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20  .  typedef long 
2b10: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
2b20: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
2b30: 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c   unsigned long l
2b40: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75  ong int sqlite_u
2b50: 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79  int64;.#endif.ty
2b60: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74  pedef sqlite_int
2b70: 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  64 sqlite3_int64
2b80: 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  ;.typedef sqlite
2b90: 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
2ba0: 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49  uint64;../*.** I
2bb0: 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20  f compiling for 
2bc0: 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74  a processor that
2bd0: 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20   lacks floating 
2be0: 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a  point support,.*
2bf0: 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74  * substitute int
2c00: 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e  eger for floatin
2c10: 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64  g-point..*/.#ifd
2c20: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46  ef SQLITE_OMIT_F
2c30: 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20  LOATING_POINT.# 
2c40: 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71  define double sq
2c50: 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64  lite3_int64.#end
2c60: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
2c70: 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61  EF: Closing A Da
2c80: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2c90: 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a  n.** DESTRUCTOR:
2ca0: 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
2cb0: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  The sqlite3_clos
2cc0: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
2cd0: 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69  close_v2() routi
2ce0: 6e 65 73 20 61 72 65 20 64 65 73 74 72 75 63 74  nes are destruct
2cf0: 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ors.** for the [
2d00: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e  sqlite3] object.
2d10: 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
2d20: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e  lite3_close() an
2d30: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  d sqlite3_close_
2d40: 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c  v2() return [SQL
2d50: 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68  ITE_OK] if.** th
2d60: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2d70: 63 74 20 69 73 20 73 75 63 63 65 73 73 66 75 6c  ct is successful
2d80: 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64  ly destroyed and
2d90: 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a   all associated.
2da0: 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61 72 65  ** resources are
2db0: 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a   deallocated..**
2dc0: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
2dd0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2de0: 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
2df0: 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70  th unfinalized p
2e00: 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2e10: 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73  ments or unfinis
2e20: 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  hed sqlite3_back
2e30: 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  up objects then 
2e40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a  sqlite3_close().
2e50: 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68  ** will leave th
2e60: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2e70: 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72  ction open and r
2e80: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
2e90: 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  SY]..** ^If sqli
2ea0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2eb0: 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e  s called with un
2ec0: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72  finalized prepar
2ed0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed statements.**
2ee0: 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68   and/or unfinish
2ef0: 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  ed sqlite3_backu
2f00: 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  ps, then the dat
2f10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2f20: 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75   becomes.** an u
2f30: 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22  nusable "zombie"
2f40: 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f   which will auto
2f50: 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61  matically be dea
2f60: 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68  llocated when th
2f70: 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72  e.** last prepar
2f80: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
2f90: 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65  finalized or the
2fa0: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61   last sqlite3_ba
2fb0: 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73  ckup is.** finis
2fc0: 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65  hed.  The sqlite
2fd0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74  3_close_v2() int
2fe0: 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64  erface is intend
2ff0: 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a  ed for use with.
3000: 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65  ** host language
3010: 73 20 74 68 61 74 20 61 72 65 20 67 61 72 62 61  s that are garba
3020: 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e  ge collected, an
3030: 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 64 65  d where the orde
3040: 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65  r in which.** de
3050: 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 63 61  structors are ca
3060: 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 61 72  lled is arbitrar
3070: 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  y..**.** Applica
3080: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71  tions should [sq
3090: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
30a0: 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b   finalize] all [
30b0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30c0: 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  nts],.** [sqlite
30d0: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63  3_blob_close | c
30e0: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20  lose] all [BLOB 
30f0: 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a  handles], and .*
3100: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
3110: 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73  p_finish | finis
3120: 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  h] all [sqlite3_
3130: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3140: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
3150: 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  th the [sqlite3]
3160: 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f   object prior to
3170: 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63   attempting to c
3180: 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e  lose the object.
3190: 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33    ^If.** sqlite3
31a0: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63  _close_v2() is c
31b0: 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61  alled on a [data
31c0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
31d0: 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a   that still has.
31e0: 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b  ** outstanding [
31f0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
3200: 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64  nts], [BLOB hand
3210: 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  les], and/or.** 
3220: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3230: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74   objects then it
3240: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
3250: 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61  _OK] and the dea
3260: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
3270: 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65 66  resources is def
3280: 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20  erred until all 
3290: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32a0: 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e  ents], [BLOB han
32b0: 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73  dles],.** and [s
32c0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
32d0: 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20  bjects are also 
32e0: 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a  destroyed..**.**
32f0: 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33   ^If an [sqlite3
3300: 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74  ] object is dest
3310: 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74 72  royed while a tr
3320: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65  ansaction is ope
3330: 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61  n,.** the transa
3340: 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74  ction is automat
3350: 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
3360: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20  ck..**.** The C 
3370: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
3380: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
3390: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
33a0: 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73  se_v2(C)].** mus
33b0: 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55  t be either a NU
33c0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72  LL.** pointer or
33d0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62   an [sqlite3] ob
33e0: 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74  ject pointer obt
33f0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3400: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
3410: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
3420: 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
3430: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
3440: 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c  nd not previousl
3450: 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61  y closed..** ^Ca
3460: 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c  lling sqlite3_cl
3470: 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ose() or sqlite3
3480: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68  _close_v2() with
3490: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
34a0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  ** argument is a
34b0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
34c0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
34d0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
34e0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
34f0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
3500: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69  e3_close_v2(sqli
3510: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  te3*);../*.** Th
3520: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c  e type for a cal
3530: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a  lback function..
3540: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63  ** This is legac
3550: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64  y and deprecated
3560: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65  .  It is include
3570: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
3580: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
3590: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63  y and is not doc
35a0: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65  umented..*/.type
35b0: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65  def int (*sqlite
35c0: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  3_callback)(void
35d0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68  *,int,char**, ch
35e0: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ar**);../*.** CA
35f0: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70  PI3REF: One-Step
3600: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e   Query Execution
3610: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45   Interface.** ME
3620: 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
3630: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
3640: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65  exec() interface
3650: 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63   is a convenienc
3660: 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  e wrapper around
3670: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
3680: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
3690: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e  ite3_step()], an
36a0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
36b0: 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20  ize()],.** that 
36c0: 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63  allows an applic
36d0: 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c  ation to run mul
36e0: 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73  tiple statements
36f0: 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f   of SQL.** witho
3700: 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65  ut having to use
3710: 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65   a lot of C code
3720: 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  . .**.** ^The sq
3730: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74  lite3_exec() int
3740: 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f  erface runs zero
3750: 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65   or more UTF-8 e
3760: 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63  ncoded,.** semic
3770: 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51  olon-separate SQ
3780: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
3790: 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64  sed into its 2nd
37a0: 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e   argument,.** in
37b0: 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20   the context of 
37c0: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
37d0: 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64  nnection] passed
37e0: 20 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a   in as its 1st.*
37f0: 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66  * argument.  ^If
3800: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   the callback fu
3810: 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72  nction of the 3r
3820: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
3830: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3840: 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
3850: 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  n it is invoked 
3860: 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20  for each result 
3870: 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75  row.** coming ou
3880: 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74  t of the evaluat
3890: 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
38a0: 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67  s.  ^The 4th arg
38b0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
38c0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65  te3_exec() is re
38d0: 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f  layed through to
38e0: 20 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e   the 1st argumen
38f0: 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c  t of each.** cal
3900: 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e  lback invocation
3910: 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  .  ^If the callb
3920: 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ack pointer to s
3930: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3940: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e   is NULL, then n
3950: 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76  o callback is ev
3960: 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72  er invoked and r
3970: 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a  esult rows are.*
3980: 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  * ignored..**.**
3990: 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63   ^If an error oc
39a0: 63 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75  curs while evalu
39b0: 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74  ating the SQL st
39c0: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
39d0: 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
39e0: 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65  exec(), then exe
39f0: 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75  cution of the cu
3a00: 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20  rrent statement 
3a10: 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62  stops and.** sub
3a20: 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e  sequent statemen
3a30: 74 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20  ts are skipped. 
3a40: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3a50: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a60: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e  3_exec().** is n
3a70: 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79  ot NULL then any
3a80: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
3a90: 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  s written into m
3aa0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a  emory obtained.*
3ab0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3ac0: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61  malloc()] and pa
3ad0: 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67  ssed back throug
3ae0: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3af0: 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  ter..** To avoid
3b00: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74   memory leaks, t
3b10: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
3b20: 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71  hould invoke [sq
3b30: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a  lite3_free()].**
3b40: 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   on error messag
3b50: 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
3b60: 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ed through the 5
3b70: 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a  th parameter of.
3b80: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3b90: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
3ba0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3bb0: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
3bc0: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
3bd0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3be0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3bf0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
3c00: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
3c10: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
3c20: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
3c30: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
3c40: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3c50: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
3c60: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
3c70: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
3c80: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3c90: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
3ca0: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
3cb0: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
3cc0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
3cd0: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
3ce0: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
3cf0: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
3d00: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
3d10: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
3d20: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
3d30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
3d40: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
3d50: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3d60: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3d70: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
3d80: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
3d90: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
3da0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3db0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3dc0: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
3dd0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3de0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3df0: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
3e00: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
3e10: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
3e20: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
3e30: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
3e40: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
3e50: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
3e60: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
3e70: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
3e80: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
3e90: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3ea0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3eb0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
3ec0: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3ed0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
3ee0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3ef0: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
3f00: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3f10: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
3f20: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
3f30: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
3f40: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
3f50: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
3f60: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3f70: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
3f80: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
3f90: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
3fa0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3fb0: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
3fc0: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
3fd0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
3fe0: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
3ff0: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
4000: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
4010: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
4020: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
4030: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
4040: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
4050: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
4060: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
4070: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
4080: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
4090: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
40a0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
40b0: 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
40c0: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
40d0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
40e0: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
40f0: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
4100: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
4110: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
4120: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
4130: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
4140: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
4150: 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
4160: 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74  ied by.**      t
4170: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
4180: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
4190: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
41a0: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
41b0: 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ng..** <li> The 
41c0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
41d0: 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20   not modify the 
41e0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
41f0: 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a  xt passed into.*
4200: 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 20 70  *      the 2nd p
4210: 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
4220: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
4230: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4240: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
4250: 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  /ul>.*/.SQLITE_A
4260: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  PI int sqlite3_e
4270: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  xec(.  sqlite3*,
4280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42a0: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
42b0: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
42c0: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   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 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
42f0: 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
4300: 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b    int (*callback
4310: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
4320: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20  **,char**),  /* 
4330: 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  Callback functio
4340: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  n */.  void *,  
4350: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e    /* 1st argumen
4380: 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f  t to callback */
4390: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
43a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
43c0: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
43d0: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f  en here */.);../
43e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
43f0: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
4400: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
4410: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e   code definition
4420: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
4430: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
4440: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
4450: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
4460: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
4470: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
4480: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63   to indicate suc
4490: 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e  cess or failure.
44a0: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72  .**.** New error
44b0: 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64   codes may be ad
44c0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65  ded in future ve
44d0: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
44e0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
44f0: 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : [extended resu
4500: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4510: 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ons].*/.#define 
4520: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
4530: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4540: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4550: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4560: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
4570: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
4580: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
4590: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
45a0: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
45b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
45c0: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
45d0: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
45e0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
45f0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
4600: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
4610: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
4620: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
4630: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4640: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4650: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4660: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
4670: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4690: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
46a0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
46b0: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
46c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
46d0: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
46e0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
46f0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
4700: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4710: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
4720: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
4730: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4740: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4750: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4760: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
4770: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4780: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4790: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
47a0: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
47b0: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
47c0: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
47d0: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
47e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
47f0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
4800: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
4810: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
4820: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
4830: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4840: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4850: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4860: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
4870: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4880: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4890: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
48a0: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
48b0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
48c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
48d0: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
48e0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
48f0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
4900: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
4910: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4920: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
4930: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4940: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4950: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4960: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4970: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4980: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4990: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
49a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
49b0: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
49c0: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
49d0: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
49e0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
49f0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
4a00: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
4a10: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
4a20: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
4a30: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4a40: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4a50: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4a70: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4a80: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4a90: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4aa0: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4ab0: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4ac0: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4ad0: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
4b00: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
4b10: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
4b20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4b30: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4b40: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4b50: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4b60: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4b70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4b80: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4b90: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4ba0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4bb0: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4bc0: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4bd0: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
4be0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
4c00: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
4c10: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
4c20: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
4c30: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4c40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4c50: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4c60: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4c70: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4c80: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4c90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4ca0: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4cb0: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4cc0: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4cd0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4ce0: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4cf0: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4d00: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4d10: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4d20: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4d30: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4d40: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4d50: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d70: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4d80: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4d90: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4da0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4db0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4dc0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4dd0: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4de0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4df0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4e00: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4e10: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4e20: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
4e30: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
4e40: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
4e50: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
4e60: 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a  of 30 integer.**
4e70: 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e   [result codes].
4e80: 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72    However, exper
4e90: 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20  ience has shown 
4ea0: 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20  that many of.** 
4eb0: 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64  these result cod
4ec0: 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73  es are too coars
4ed0: 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79  e-grained.  They
4ee0: 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20   do not provide 
4ef0: 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72  as.** much infor
4f00: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f  mation about pro
4f10: 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d  blems as program
4f20: 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e  mers might like.
4f30: 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74    In an effort t
4f40: 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69  o.** address thi
4f50: 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  s, newer version
4f60: 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72  s of SQLite (ver
4f70: 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61 74 65  sion 3.3.8 [date
4f80: 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e 64  of:3.3.8].** and
4f90: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4fa0: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4fb0: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4fc0: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4fd0: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4fe0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4ff0: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
5000: 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72  hese [extended r
5010: 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65  esult codes] are
5020: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
5030: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
5040: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
5050: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
5060: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
5070: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
5080: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20  _codes()] API.  
5090: 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64  Or, the extended
50a0: 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65   code for.** the
50b0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72   most recent err
50c0: 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  or can be obtain
50d0: 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
50e0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
50f0: 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65  rcode()]..*/.#de
5100: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5110: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
5120: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5130: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
5140: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5150: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
5160: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5170: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5180: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5190: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
51a0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51b0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
51c0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
51d0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
51e0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51f0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5200: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
5210: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
5220: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5230: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
5240: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
5250: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
5260: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5270: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5280: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
5290: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
52a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
52b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
52d0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
52e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
52f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5300: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
5310: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5320: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
5330: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5340: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
5350: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5360: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
5370: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5380: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
5390: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
53a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
53b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
53c0: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
53d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
53e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
53f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5400: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
5410: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5420: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
5430: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5440: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
5450: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
5460: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
5470: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5480: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
5490: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
54a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
54b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
54c0: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
54d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
54e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
54f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5500: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
5510: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
5520: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
5530: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5540: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
5550: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5560: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
5570: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5580: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
5590: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
55a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
55b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
55c0: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
55d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
55e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
55f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5600: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20  TE_IOERR_SHMMAP 
5610: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5620: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c  TE_IOERR | (21<<
5630: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5640: 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20  TE_IOERR_SEEK   
5650: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5660: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c  TE_IOERR | (22<<
5670: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5680: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f  TE_IOERR_DELETE_
5690: 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49  NOENT      (SQLI
56a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c  TE_IOERR | (23<<
56b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
56c0: 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20  TE_IOERR_MMAP   
56d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
56e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c  TE_IOERR | (24<<
56f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5700: 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50  TE_IOERR_GETTEMP
5710: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5720: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c  TE_IOERR | (25<<
5730: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5740: 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54  TE_IOERR_CONVPAT
5750: 48 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  H          (SQLI
5760: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c  TE_IOERR | (26<<
5770: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5780: 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20  TE_IOERR_VNODE  
5790: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
57a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c  TE_IOERR | (27<<
57b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
57c0: 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 20  TE_IOERR_AUTH   
57d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
57e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c  TE_IOERR | (28<<
57f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5800: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
5810: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
5820: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5830: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5840: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5850: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5860: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5870: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5880: 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48  LITE_BUSY_SNAPSH
5890: 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51  OT           (SQ
58a0: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
58b0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
58c0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e  QLITE_CANTOPEN_N
58d0: 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53  OTEMPDIR      (S
58e0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
58f0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5900: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5910: 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20  _ISDIR          
5920: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5930: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5940: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5950: 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20  EN_FULLPATH     
5960: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5970: 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  EN | (3<<8)).#de
5980: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5990: 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20  OPEN_CONVPATH   
59a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
59b0: 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23  OPEN | (4<<8)).#
59c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
59d0: 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20  RRUPT_VTAB      
59e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
59f0: 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a  RRUPT | (1<<8)).
5a00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5a10: 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59  EADONLY_RECOVERY
5a20: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5a30: 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29  EADONLY | (1<<8)
5a40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a50: 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f  _READONLY_CANTLO
5a60: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
5a70: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c  _READONLY | (2<<
5a80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5a90: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c  TE_READONLY_ROLL
5aa0: 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  BACK       (SQLI
5ab0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33  TE_READONLY | (3
5ac0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ad0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42  LITE_READONLY_DB
5ae0: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 53 51  MOVED        (SQ
5af0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5b00: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5b10: 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c  SQLITE_ABORT_ROL
5b20: 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28  LBACK          (
5b30: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28  SQLITE_ABORT | (
5b40: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b50: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b60: 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53  _CHECK        (S
5b70: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b80: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5b90: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5ba0: 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20  AINT_COMMITHOOK 
5bb0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5bc0: 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  AINT | (2<<8)).#
5bd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5be0: 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e  NSTRAINT_FOREIGN
5bf0: 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  KEY   (SQLITE_CO
5c00: 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38  NSTRAINT | (3<<8
5c10: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5c20: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e  E_CONSTRAINT_FUN
5c30: 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54  CTION     (SQLIT
5c40: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5c50: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5c60: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c70: 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53  _NOTNULL      (S
5c80: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c90: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
5ca0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5cb0: 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20  AINT_PRIMARYKEY 
5cc0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5cd0: 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23  AINT | (6<<8)).#
5ce0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5cf0: 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52  NSTRAINT_TRIGGER
5d00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5d10: 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38  NSTRAINT | (7<<8
5d20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49  E_CONSTRAINT_UNI
5d40: 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54  QUE       (SQLIT
5d50: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5d60: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
5d70: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5d80: 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53  _VTAB         (S
5d90: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5da0: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5db0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5dc0: 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20  AINT_ROWID      
5dd0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5de0: 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23  AINT |(10<<8)).#
5df0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
5e00: 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c  TICE_RECOVER_WAL
5e10: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f        (SQLITE_NO
5e20: 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23  TICE | (1<<8)).#
5e30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
5e40: 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c  TICE_RECOVER_ROL
5e50: 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f  LBACK (SQLITE_NO
5e60: 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23  TICE | (2<<8)).#
5e70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41  define SQLITE_WA
5e80: 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20  RNING_AUTOINDEX 
5e90: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41        (SQLITE_WA
5ea0: 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a  RNING | (1<<8)).
5eb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
5ec0: 55 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20  UTH_USER        
5ed0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
5ee0: 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UTH | (1<<8)).#d
5ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f  efine SQLITE_OK_
5f00: 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59  LOAD_PERMANENTLY
5f10: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20       (SQLITE_OK 
5f20: 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a  | (1<<8))../*.**
5f30: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
5f40: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f   For File Open O
5f50: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  perations.**.** 
5f60: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
5f70: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
5f80: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
5f90: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
5fa0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
5fb0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
5fc0: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
5fd0: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
5fe0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
5ff0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
6000: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6010: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
6020: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
6030: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0001  /* Ok for 
6040: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6050: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6060: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
6070: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
6080: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0002  /* Ok for 
6090: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
60a0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
60b0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
60c0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
60d0: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0004  /* Ok for 
60e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
60f0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6100: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
6110: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
6120: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0008  /* VFS onl
6130: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6140: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
6150: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
6160: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0010  /* VFS onl
6170: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6180: 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f  ITE_OPEN_AUTOPRO
6190: 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30  XY        0x0000
61a0: 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0020  /* VFS onl
61b0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
61c0: 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20  ITE_OPEN_URI    
61d0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
61e0: 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0040  /* Ok for 
61f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6200: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6210: 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20  ITE_OPEN_MEMORY 
6220: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6230: 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0080  /* Ok for 
6240: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6250: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6260: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
6270: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6280: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0100  /* VFS onl
6290: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
62a0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
62b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
62c0: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0200  /* VFS onl
62d0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
62e0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
62f0: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
6300: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0400  /* VFS onl
6310: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6320: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
6330: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
6340: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0800  /* VFS onl
6350: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6360: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
6370: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
6380: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  1000  /* VFS onl
6390: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
63a0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
63b0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
63c0: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  2000  /* VFS onl
63d0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
63e0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
63f0: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
6400: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  4000  /* VFS onl
6410: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6420: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
6430: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6440: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  8000  /* Ok for 
6450: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6460: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6470: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
6480: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
6490: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
64a0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
64b0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
64c0: 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
64d0: 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32  ACHE      0x0002
64e0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
64f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6500: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6510: 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
6520: 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34  CACHE     0x0004
6530: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
6540: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6550: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6560: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20  ITE_OPEN_WAL    
6570: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38            0x0008
6580: 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0000  /* VFS onl
6590: 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65  y */../* Reserve
65a0: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  d:              
65b0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46             0x00F
65c0: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  00000 */../*.** 
65d0: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65  CAPI3REF: Device
65e0: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73   Characteristics
65f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
6600: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
6610: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
6620: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6630: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
6640: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
6650: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
6660: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  tor of these.** 
6670: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
6680: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
6690: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
66a0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
66b0: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
66c0: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
66d0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
66e0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
66f0: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
6700: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6710: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6720: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
6730: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
6740: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
6750: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6760: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
6770: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
6780: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
6790: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
67a0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
67b0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
67c0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
67d0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
67e0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
67f0: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
6800: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6810: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
6820: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
6830: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
6840: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
6850: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
6860: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
6870: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
6880: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
6890: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
68a0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
68b0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
68c0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
68d0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
68e0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
68f0: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
6900: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
6910: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
6920: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
6930: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45  e().  The SQLITE
6940: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6950: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65  _OVERWRITE prope
6960: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6970: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66  * after reboot f
6980: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68  ollowing a crash
6990: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20   or power loss, 
69a0: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69  the only bytes i
69b0: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74  n a.** file that
69c0: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74   were written at
69d0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
69e0: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76   level might hav
69f0: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64  e changed.** and
6a00: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62   that adjacent b
6a10: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73  ytes, even bytes
6a20: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
6a30: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67   sector are.** g
6a40: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
6a50: 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
6a60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
6a70: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
6a80: 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63  EN.** flag indic
6a90: 61 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65  ates that a file
6aa0: 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74   cannot be delet
6ab0: 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54  ed when open.  T
6ac0: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43  he.** SQLITE_IOC
6ad0: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61  AP_IMMUTABLE fla
6ae0: 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  g indicates that
6af0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a   the file is on.
6b00: 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64  ** read-only med
6b10: 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65  ia and cannot be
6b20: 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79   changed even by
6b30: 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a   processes with.
6b40: 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76  ** elevated priv
6b50: 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69  ileges..*/.#defi
6b60: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b70: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
6b80: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6b90: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6ba0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6bb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6bc0: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
6bd0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6be0: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20  OMIC1K          
6bf0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
6c00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6c10: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
6c20: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6c30: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
6c40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6c50: 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC4K            
6c60: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
6c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6c80: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
6c90: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6ca0: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
6cb0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6cc0: 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  16K             
6cd0: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
6ce0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6cf0: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
6d00: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6d10: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
6d20: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6d30: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6d40: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
6d50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6d60: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20  AFE_APPEND      
6d70: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
6d80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6d90: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6da0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6db0: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
6dc0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
6dd0: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
6de0: 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23  EN  0x00000800.#
6df0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6e00: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6e10: 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30  ERWRITE    0x000
6e20: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
6e30: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6e40: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  ABLE            
6e50: 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a    0x00002000../*
6e60: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
6e70: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
6e80: 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  s.**.** SQLite u
6e90: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ses one of these
6ea0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6eb0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
6ec0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
6ed0: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
6ee0: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
6ef0: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
6f00: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
6f10: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6f20: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
6f30: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
6f40: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
6f50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6f60: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
6f70: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6f80: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
6f90: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
6fa0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6fb0: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
6fc0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
6fd0: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
6fe0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
6ff0: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
7000: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
7010: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
7020: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
7030: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20  method of an.** 
7040: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7050: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75  ods] object it u
7060: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
7070: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e  n of.** these in
7080: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
7090: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
70a0: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
70b0: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
70c0: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73  DATAONLY flag is
70d0: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20   used, it means 
70e0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63  that the.** sync
70f0: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20   operation only 
7100: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64  needs to flush d
7110: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72  ata to mass stor
7120: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69  age.  Inode.** i
7130: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20  nformation need 
7140: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20  not be flushed. 
7150: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
7160: 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c  r bits of the fl
7170: 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49  ag.** equal SQLI
7180: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20  TE_SYNC_NORMAL, 
7190: 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73  that means to us
71a0: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
71b0: 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49   semantics..** I
71c0: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
71d0: 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49   bits equal SQLI
71e0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68  TE_SYNC_FULL, th
71f0: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  at means.** to u
7200: 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c  se Mac OS X styl
7210: 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65  e fullsync inste
7220: 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a  ad of fsync()..*
7230: 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66  *.** Do not conf
7240: 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53  use the SQLITE_S
7250: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
7260: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
7270: 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68  flags.** with th
7280: 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  e [PRAGMA synchr
7290: 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e  onous]=NORMAL an
72a0: 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  d [PRAGMA synchr
72b0: 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73  onous]=FULL.** s
72c0: 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73  ettings.  The [s
72d0: 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d  ynchronous pragm
72e0: 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68  a] determines wh
72f0: 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  en calls to the.
7300: 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74  ** xSync VFS met
7310: 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70  hod occur and ap
7320: 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20  plies uniformly 
7330: 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66  across all platf
7340: 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  orms..** The SQL
7350: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7360: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7370: 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72  FULL flags deter
7380: 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72  mine how.** ener
7390: 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75  getic or rigorou
73a0: 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68  s or forceful th
73b0: 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  e sync operation
73c0: 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c  s are and.** onl
73d0: 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65  y make a differe
73e0: 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66  nce on Mac OSX f
73f0: 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53  or the default S
7400: 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28  QLite code..** (
7410: 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20  Third-party VFS 
7420: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7430: 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20  might also make 
7440: 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  the distinction.
7450: 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
7460: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7470: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7480: 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68  LL, but among th
7490: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73  e.** operating s
74a0: 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20  ystems natively 
74b0: 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
74c0: 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53  ite, only Mac OS
74d0: 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74  X.** cares about
74e0: 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e   the difference.
74f0: 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ).*/.#define SQL
7500: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7510: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
7520: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7530: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
7540: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
7550: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
7560: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
7570: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
7580: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
7590: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
75a0: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
75b0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
75c0: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
75d0: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
75e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
75f0: 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20   | OS interface 
7600: 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64  layer].  Individ
7610: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ual OS interface
7620: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
7630: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
7640: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
7650: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
7660: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
7670: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
7680: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
7690: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
76a0: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
76b0: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
76c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
76d0: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
76e0: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
76f0: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
7700: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
7710: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
7720: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7730: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
7740: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
7750: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
7760: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
7770: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7780: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
7790: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
77a0: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
77b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
77c0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
77d0: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
77e0: 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45  s Object.**.** E
77f0: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
7800: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
7810: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7820: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a  od populates an.
7830: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7840: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f  ] object (or, mo
7850: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73  re commonly, a s
7860: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
7870: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
7880: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20   object) with a 
7890: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
78a0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
78b0: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  bject..** This o
78c0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
78d0: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  e methods used t
78e0: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
78f0: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  s operations.** 
7900: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
7910: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65   file represente
7920: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7930: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a  3_file] object..
7940: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71  **.** If the [sq
7950: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7960: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
7970: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7980: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
7990: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
79a0: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
79b0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
79c0: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
79d0: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
79e0: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
79f0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7a00: 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74  Open] reported t
7a10: 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20  hat it failed.  
7a20: 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20  The.** only way 
7a30: 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c  to prevent a cal
7a40: 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c  l to xClose foll
7a50: 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b  owing a failed [
7a60: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7a70: 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65  n].** is for the
7a80: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7a90: 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20  pen] to set the 
7aa0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
7ab0: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a  thods element.**
7ac0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
7ad0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
7ae0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
7af0: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
7b00: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
7b10: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
7b20: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
7b30: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
7b40: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
7b50: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
7b60: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
7b70: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
7b80: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
7b90: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
7ba0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
7bb0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
7bc0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
7bd0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
7be0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
7bf0: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
7c00: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
7c10: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
7c20: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
7c30: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
7c40: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
7c50: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7c60: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
7c70: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7c80: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
7c90: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7ca0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
7cb0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7cc0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
7cd0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7ce0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
7cf0: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
7d00: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
7d10: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
7d20: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
7d30: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
7d40: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
7d50: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
7d60: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
7d70: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
7d80: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
7d90: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
7da0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
7db0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
7dc0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
7dd0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
7de0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
7df0: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
7e00: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
7e10: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
7e20: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
7e30: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
7e40: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
7e50: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
7e60: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
7e70: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
7e80: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7e90: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
7ea0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
7eb0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
7ec0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7ed0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
7ee0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
7ef0: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
7f00: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
7f10: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
7f20: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
7f30: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
7f40: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
7f50: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
7f60: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
7f70: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
7f80: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
7f90: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
7fa0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
7fb0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
7fc0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
7fd0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
7fe0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
7ff0: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
8000: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
8010: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
8020: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
8030: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
8040: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
8050: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
8060: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
8070: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
8080: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
8090: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
80a0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
80b0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
80c0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
80d0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
80e0: 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e  ..** A [file con
80f0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c  trol opcodes | l
8100: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20  ist of opcodes] 
8110: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73  less than 100 is
8120: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41   available..** A
8130: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
8140: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d   define a custom
8150: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8160: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
8170: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74  opcodes.** great
8180: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
8190: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20  void conflicts. 
81a0: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
81b0: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  ions should.** r
81c0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
81d0: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65  TFOUND] for file
81e0: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
81f0: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
8200: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a  t.** recognize..
8210: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
8220: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
8230: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
8240: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
8250: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
8260: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
8270: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
8280: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
8290: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
82a0: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
82b0: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
82c0: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
82d0: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
82e0: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
82f0: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
8300: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
8310: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
8320: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
8330: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
8340: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
8350: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8360: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8370: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
8380: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8390: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <li> 
83a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
83b0: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <li> 
83c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
83d0: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <li> 
83e0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
83f0: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <li> 
8400: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8410: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
8420: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8430: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <li>
8440: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8450: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
8460: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8470: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
8480: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8490: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
84a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
84b0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
84c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
84d0: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
84e0: 45 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20  E_WHEN_OPEN].** 
84f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8500: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
8510: 52 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  RWRITE].** <li> 
8520: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d  [SQLITE_IOCAP_IM
8530: 4d 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c 2f 75 6c  MUTABLE].** </ul
8540: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
8550: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
8560: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8570: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
8580: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
8590: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
85a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
85b0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
85c0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
85d0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
85e0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
85f0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
8600: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
8610: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
8620: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
8630: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
8640: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8650: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8660: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8670: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8680: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8690: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
86a0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
86b0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
86c0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
86d0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
86e0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
86f0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
8700: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8710: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
8720: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8730: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
8740: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
8750: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8760: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8770: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
8780: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
8790: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
87a0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
87b0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
87c0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
87d0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
87e0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
87f0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
8800: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
8810: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8820: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
8830: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
8840: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
8850: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8860: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
8870: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
8880: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
8890: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
88a0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
88b0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
88c0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
88d0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
88e0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
88f0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
8900: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
8910: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8920: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
8930: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
8940: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8950: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8960: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
8970: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
8980: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
8990: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
89a0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
89b0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
89c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
89d0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
89e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
89f0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8a00: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
8a10: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
8a20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8a30: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
8a40: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
8a50: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8a60: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8a70: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
8a80: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
8a90: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
8aa0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
8ab0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
8ac0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
8ad0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
8ae0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8af0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
8b00: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
8b10: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
8b20: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8b30: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
8b40: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
8b50: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
8b60: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8b70: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8b80: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
8b90: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
8ba0: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
8bb0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
8bc0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
8bd0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
8be0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8bf0: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
8c00: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
8c10: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
8c20: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
8c30: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8c40: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
8c50: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
8c60: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
8c70: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8c80: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8c90: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
8ca0: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
8cb0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8cc0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
8cd0: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
8ce0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
8cf0: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
8d00: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8d10: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
8d20: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8d30: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8d40: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
8d50: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
8d60: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
8d70: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
8d80: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
8d90: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
8da0: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
8db0: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20  trol Opcodes.** 
8dc0: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20  KEYWORDS: {file 
8dd0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d  control opcodes}
8de0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
8df0: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  pcode}.**.** The
8e00: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
8e10: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
8e20: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
8e30: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
8e40: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
8e50: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
8e60: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
8e70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8e80: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
8e90: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  face..**.** <ul>
8ea0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8eb0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8ec0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8ed0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8ee0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
8ef0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
8f00: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
8f10: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
8f20: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
8f30: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
8f40: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
8f50: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
8f60: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
8f70: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
8f80: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
8f90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
8fa0: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
8fb0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
8fc0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
8fd0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
8fe0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
8ff0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
9000: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
9010: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
9020: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
9030: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20   testing and is 
9040: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77  only available w
9050: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hen the SQLITE_T
9060: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  EST.** compile-t
9070: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  ime option is us
9080: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
9090: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
90a0: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
90b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
90c0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
90d0: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
90e0: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
90f0: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
9100: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
9110: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9120: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
9130: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
9140: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
9150: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
9160: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
9170: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
9180: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
9190: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
91a0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
91b0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
91c0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
91d0: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
91e0: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
91f0: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
9200: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
9210: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
9220: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
9230: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9240: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
9250: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
9260: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
9270: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
9280: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
9290: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
92a0: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
92b0: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
92c0: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
92d0: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
92e0: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
92f0: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
9300: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
9310: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9320: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
9330: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
9340: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
9350: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9360: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
9370: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
9380: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
9390: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
93a0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
93b0: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
93c0: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
93d0: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
93e0: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
93f0: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
9400: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
9410: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
9420: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
9430: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9440: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
9450: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
9460: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9470: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
9480: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
9490: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
94a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
94b0: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
94c0: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
94d0: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
94e0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
94f0: 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54   See also [SQLIT
9500: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
9510: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  POINTER]..**.** 
9520: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9530: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
9540: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
9550: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
9560: 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  L_POINTER] opcod
9570: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
9580: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
9590: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
95a0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
95b0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
95c0: 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28  e journal file (
95d0: 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72  either.** the [r
95e0: 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d  ollback journal]
95f0: 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61   or the [write-a
9600: 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61  head log]) for a
9610: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
9620: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
9630: 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53  on.  See also [S
9640: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
9650: 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a  _POINTER]..**.**
9660: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9670: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
9680: 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20  ]].** No longer 
9690: 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  in use..**.** <l
96a0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
96b0: 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SYNC]].** The [
96c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
96d0: 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  C] opcode is gen
96e0: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
96f0: 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a  y by SQLite and.
9700: 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  ** sent to the V
9710: 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62  FS immediately b
9720: 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20  efore the xSync 
9730: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
9740: 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61  d on a.** databa
9750: 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74  se file descript
9760: 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78  or. Or, if the x
9770: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e  Sync method is n
9780: 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62  ot invoked .** b
9790: 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20  ecause the user 
97a0: 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53  has configured S
97b0: 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b  QLite with .** [
97c0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
97d0: 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63  us | PRAGMA sync
97e0: 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20  hronous=OFF] it 
97f0: 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c  is invoked in pl
9800: 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78  ace .** of the x
9810: 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20  Sync method. In 
9820: 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20  most cases, the 
9830: 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
9840: 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20   passed with.** 
9850: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
9860: 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76  l is NULL. Howev
9870: 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62  er, if the datab
9880: 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e  ase file is bein
9890: 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70  g synced.** as p
98a0: 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64  art of a multi-d
98b0: 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20  atabase commit, 
98c0: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  the argument poi
98d0: 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72  nts to a nul-ter
98e0: 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
98f0: 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
9900: 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61   transactions ma
9910: 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c  ster-journal fil
9920: 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68  e name. VFSes th
9930: 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65  at .** do not ne
9940: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73  ed this signal s
9950: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
9960: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
9970: 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  e. Applications 
9980: 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  .** should not c
9990: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
99a0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
99b0: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
99c0: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a   doing so may .*
99d0: 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70  * disrupt the op
99e0: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
99f0: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
9a00: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
9a10: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
9a20: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9a30: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d  COMMIT_PHASETWO]
9a40: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9a50: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
9a60: 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69  ASETWO] opcode i
9a70: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
9a80: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
9a90: 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20  .** and sent to 
9aa0: 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20  the VFS after a 
9ab0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20  transaction has 
9ac0: 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69  been committed i
9ad0: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75  mmediately.** bu
9ae0: 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74  t before the dat
9af0: 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65  abase is unlocke
9b00: 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  d. VFSes that do
9b10: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
9b20: 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20  ignal.** should 
9b30: 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
9b40: 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70  this opcode. App
9b50: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
9b60: 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71   not call.** [sq
9b70: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9b80: 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20  ol()] with this 
9b90: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20  opcode as doing 
9ba0: 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74  so may disrupt t
9bb0: 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  he .** operation
9bc0: 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69   of the speciali
9bd0: 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64  zed VFSes that d
9be0: 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a  o require it.  .
9bf0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9c00: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
9c10: 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68  V_RETRY]].** ^Th
9c20: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9c30: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20  WIN32_AV_RETRY] 
9c40: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9c50: 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f  o configure auto
9c60: 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63  matic.** retry c
9c70: 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76  ounts and interv
9c80: 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20  als for certain 
9c90: 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69  disk I/O operati
9ca0: 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77  ons for the.** w
9cb0: 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20  indows [VFS] in 
9cc0: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
9cd0: 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74   robustness in t
9ce0: 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a  he presence of.*
9cf0: 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f  * anti-virus pro
9d00: 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75  grams.  By defau
9d10: 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20  lt, the windows 
9d20: 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66  VFS will retry f
9d30: 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c  ile read,.** fil
9d40: 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c  e write, and fil
9d50: 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69  e delete operati
9d60: 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d  ons up to 10 tim
9d70: 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79  es, with a delay
9d80: 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73  .** of 25 millis
9d90: 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68  econds before th
9da0: 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e  e first retry an
9db0: 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79  d with the delay
9dc0: 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62   increasing.** b
9dd0: 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20  y an additional 
9de0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9df0: 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71  with each subseq
9e00: 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69  uent retry.  Thi
9e10: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f  s.** opcode allo
9e20: 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c  ws these two val
9e30: 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20  ues (10 retries 
9e40: 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  and 25 milliseco
9e50: 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a  nds of delay).**
9e60: 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e   to be adjusted.
9e70: 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65    The values are
9e80: 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c   changed for all
9e90: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
9ea0: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20  tions.** within 
9eb0: 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73  the same process
9ec0: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
9ed0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
9ee0: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a  an array of two.
9ef0: 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72  ** integers wher
9f00: 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65  e the first inte
9f10: 67 65 72 20 69 73 20 74 68 65 20 6e 65 77 20 72  ger is the new r
9f20: 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74  etry count and t
9f30: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74  he second.** int
9f40: 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61  eger is the dela
9f50: 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e  y.  If either in
9f60: 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76  teger is negativ
9f70: 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74  e, then the sett
9f80: 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ing.** is not ch
9f90: 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61  anged but instea
9fa0: 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  d the prior valu
9fb0: 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e  e of that settin
9fc0: 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  g is written.** 
9fd0: 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65  into the array e
9fe0: 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74  ntry, allowing t
9ff0: 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79  he current retry
a000: 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a   settings to be.
a010: 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  ** interrogated.
a020: 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61    The zDbName pa
a030: 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72  rameter is ignor
a040: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
a050: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
a060: 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54  SIST_WAL]].** ^T
a070: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a080: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70  _PERSIST_WAL] op
a090: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
a0a0: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
a0b0: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b  .** persistent [
a0c0: 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61  WAL | Write Ahea
a0d0: 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20  d Log] setting. 
a0e0: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
a0f0: 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72   auxiliary.** wr
a100: 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e  ite ahead log an
a110: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
a120: 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74  files used for t
a130: 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
a140: 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61  ol.** are automa
a150: 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
a160: 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20  when the latest 
a170: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68  connection to th
a180: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c  e database.** cl
a190: 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70  oses.  Setting p
a1a0: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
a1b0: 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20  de causes those 
a1c0: 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74  files to persist
a1d0: 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e   after.** close.
a1e0: 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65    Persisting the
a1f0: 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c   files is useful
a200: 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63   when other proc
a210: 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  esses that do no
a220: 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20  t.** have write 
a230: 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68  permission on th
a240: 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74  e directory cont
a250: 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  aining the datab
a260: 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a  ase file want.**
a270: 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74   to read the dat
a280: 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74  abase file, as t
a290: 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65  he WAL and share
a2a0: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d  d memory files m
a2b0: 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20  ust exist.** in 
a2c0: 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61  order for the da
a2d0: 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61  tabase to be rea
a2e0: 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72  dable.  The four
a2f0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
a300: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
a310: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
a320: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
a330: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
a340: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
a350: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
a360: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70  s 0 to disable p
a370: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
a380: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a390: 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20  e persistent.** 
a3a0: 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  WAL mode.  If th
a3b0: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a3c0: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a3d0: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a3e0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20   current.** WAL 
a3f0: 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74  persistence sett
a400: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
a410: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
a420: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a430: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a440: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
a450: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  AFE_OVERWRITE] o
a460: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
a470: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
a480: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
a490: 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77  "powersafe-overw
a4a0: 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20  rite" or "PSOW" 
a4b0: 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53  setting.  The PS
a4c0: 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65  OW setting.** de
a4d0: 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51  termines the [SQ
a4e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
a4f0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
a500: 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44  bit of the.** xD
a510: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
a520: 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68  tics methods. Th
a530: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a540: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
a550: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a560: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
a570: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
a580: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
a590: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
a5a0: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
a5b0: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a5c0: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
a5d0: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a5e0: 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  .** mode.  If th
a5f0: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a600: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a610: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a620: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f   current.** zero
a630: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74  -damage mode set
a640: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
a650: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  [[SQLITE_FCNTL_O
a660: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
a670: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a680: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a690: 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  de is invoked by
a6a0: 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70   SQLite after op
a6b0: 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65  ening.** a write
a6c0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
a6d0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75  indicate that, u
a6e0: 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c  nless it is roll
a6f0: 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65  ed back for some
a700: 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20  .** reason, the 
a710: 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20  entire database 
a720: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65  file will be ove
a730: 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
a740: 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e  current .** tran
a750: 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73  saction. This is
a760: 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20   used by VACUUM 
a770: 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
a780: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a790: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a  CNTL_VFSNAME]].*
a7a0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a7b0: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70  CNTL_VFSNAME] op
a7c0: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
a7d0: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e   to obtain the n
a7e0: 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b  ames of.** all [
a7f0: 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46  VFSes] in the VF
a800: 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61  S stack.  The na
a810: 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56  mes are of all V
a820: 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65  FS shims and the
a830: 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d  .** final bottom
a840: 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77  -level VFS are w
a850: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
a860: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
a870: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
a880: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20  lloc()] and the 
a890: 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64  result is stored
a8a0: 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61   in the char* va
a8b0: 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74  riable.** that t
a8c0: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a8d0: 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ter of [sqlite3_
a8e0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a8f0: 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68  points to..** Th
a900: 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70  e caller is resp
a910: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65  onsible for free
a920: 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77  ing the memory w
a930: 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69  hen done.  As wi
a940: 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63  th.** all file-c
a950: 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20  ontrol actions, 
a960: 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72  there is no guar
a970: 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20  antee that this 
a980: 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  will actually.**
a990: 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43   do anything.  C
a9a0: 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e  allers should in
a9b0: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61  itialize the cha
a9c0: 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61  r* variable to a
a9d0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
a9e0: 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69   in case this fi
a9f0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f  le-control is no
aa00: 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20  t implemented.  
aa10: 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  This file-contro
aa20: 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64  l.** is intended
aa30: 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20   for diagnostic 
aa40: 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  use only..**.** 
aa50: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
aa60: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d  TL_VFS_POINTER]]
aa70: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
aa80: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
aa90: 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73  ER] opcode finds
aaa0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
aab0: 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b  e top-level.** [
aac0: 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79  VFSes] currently
aad0: 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20   in use.  ^(The 
aae0: 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a  argument X in.**
aaf0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
ab00: 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f  ntrol(db,SQLITE_
ab10: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
ab20: 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20  R,X) must be.** 
ab30: 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65  of type "[sqlite
ab40: 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69  3_vfs] **".  Thi
ab50: 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73  s opcodes will s
ab60: 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f  et *X.** to a po
ab70: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
ab80: 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a  -level VFS.)^.**
ab90: 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65   ^When there are
aba0: 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68   multiple VFS sh
abb0: 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b  ims in the stack
abc0: 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69  , this opcode fi
abd0: 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72  nds the.** upper
abe0: 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e  -most shim only.
abf0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
ac00: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
ac10: 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20  ]].** ^Whenever 
ac20: 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  a [PRAGMA] state
ac30: 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20  ment is parsed, 
ac40: 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  an [SQLITE_FCNTL
ac50: 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c  _PRAGMA] .** fil
ac60: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e  e control is sen
ac70: 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73  t to the open [s
ac80: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
ac90: 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  ect correspondin
aca0: 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61  g.** to the data
acb0: 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69  base file to whi
acc0: 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74  ch the pragma st
acd0: 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20  atement refers. 
ace0: 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ^The argument.**
acf0: 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   to the [SQLITE_
ad00: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
ad10: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e  le control is an
ad20: 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69   array of.** poi
ad30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
ad40: 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69   (char**) in whi
ad50: 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c  ch the second el
ad60: 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72  ement of the arr
ad70: 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ay.** is the nam
ad80: 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  e of the pragma 
ad90: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c  and the third el
ada0: 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67  ement is the arg
adb0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20  ument to the.** 
adc0: 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69  pragma or NULL i
add0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73  f the pragma has
ade0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e   no argument.  ^
adf0: 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  The handler for 
ae00: 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  an.** [SQLITE_FC
ae10: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
ae20: 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74   control can opt
ae30: 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65  ionally make the
ae40: 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a   first element.*
ae50: 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20  * of the char** 
ae60: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74  argument point t
ae70: 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69  o a string obtai
ae80: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
ae90: 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20  3_mprintf()].** 
aea0: 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
aeb0: 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e  t and that strin
aec0: 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  g will become th
aed0: 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20  e result of the 
aee0: 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65  pragma or.** the
aef0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
af00: 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69  f the pragma fai
af10: 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  ls. ^If the.** [
af20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
af30: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
af40: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
af50: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65  E_NOTFOUND], the
af60: 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52  n normal .** [PR
af70: 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67  AGMA] processing
af80: 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66   continues.  ^If
af90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
afa0: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
afb0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
afc0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
afd0: 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20  then the parser 
afe0: 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
aff0: 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64  .** VFS has hand
b000: 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69  led the PRAGMA i
b010: 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61  tself and the pa
b020: 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61  rser generates a
b030: 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72   no-op.** prepar
b040: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20  ed statement if 
b050: 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73  result string is
b060: 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72   NULL, or that r
b070: 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a  eturns a copy.**
b080: 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
b090: 74 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72  tring if the str
b0a0: 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e  ing is non-NULL.
b0b0: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
b0c0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b0d0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
b0e0: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
b0f0: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
b100: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
b110: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
b120: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
b130: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
b140: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
b150: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
b160: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
b170: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
b180: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
b190: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
b1a0: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
b1b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b1c0: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
b1d0: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
b1e0: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
b1f0: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
b200: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
b210: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
b220: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
b230: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
b240: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
b250: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b260: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
b270: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
b280: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b290: 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63  NDLER].** file-c
b2a0: 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e  ontrol may be in
b2b0: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
b2c0: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
b2d0: 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73  file handle.** s
b2e0: 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20  hortly after it 
b2f0: 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64  is opened in ord
b300: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20  er to provide a 
b310: 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20  custom VFS with 
b320: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65  access.** to the
b330: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73   connections bus
b340: 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
b350: 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74  ck. The argument
b360: 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69   is of type (voi
b370: 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72  d **).** - an ar
b380: 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64  ray of two (void
b390: 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20   *) values. The 
b3a0: 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61  first (void *) a
b3b0: 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a  ctually points.*
b3c0: 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  * to a function 
b3d0: 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29  of type (int (*)
b3e0: 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72  (void *)). In or
b3f0: 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68  der to invoke th
b400: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
b410: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74   busy-handler, t
b420: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
b430: 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  uld be invoked w
b440: 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28  ith the second (
b450: 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68  void *) in.** th
b460: 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f  e array as the o
b470: 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66  nly argument. If
b480: 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d   it returns non-
b490: 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f  zero, then the o
b4a0: 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  peration.** shou
b4b0: 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49  ld be retried. I
b4c0: 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72  f it returns zer
b4d0: 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46  o, the custom VF
b4e0: 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e  S should abandon
b4f0: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
b500: 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  operation..**.**
b510: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b520: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b530: 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69  ]].** ^Applicati
b540: 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68  on can invoke th
b550: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b560: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69  TEMPFILENAME] fi
b570: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f  le-control.** to
b580: 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e   have SQLite gen
b590: 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f  erate a.** tempo
b5a0: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73  rary filename us
b5b0: 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
b5c0: 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66  orithm that is f
b5d0: 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72  ollowed to gener
b5e0: 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
b5f0: 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54   filenames for T
b600: 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f  EMP tables and o
b610: 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73  ther internal us
b620: 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75  es.  The.** argu
b630: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61  ment should be a
b640: 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69   char** which wi
b650: 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74  ll be filled wit
b660: 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  h the filename.*
b670: 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  * written into m
b680: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
b690: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
b6a0: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c  loc()].  The cal
b6b0: 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e  ler should.** in
b6c0: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
b6d0: 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73  ee()] on the res
b6e0: 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d  ult to avoid a m
b6f0: 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a  emory leak..**.*
b700: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b710: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  CNTL_MMAP_SIZE]]
b720: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b730: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
b740: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b750: 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f   used to query o
b760: 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78  r set the.** max
b770: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
b780: 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ytes that will b
b790: 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72  e used for memor
b7a0: 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a  y-mapped I/O..**
b7b0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b7c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
b7d0: 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71  value of type sq
b7e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74  lite3_int64 that
b7f0: 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f  .** is an adviso
b800: 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ry maximum numbe
b810: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
b820: 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79  e file to memory
b830: 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f   map.  The.** po
b840: 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69  inter is overwri
b850: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c  tten with the ol
b860: 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69  d value.  The li
b870: 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  mit is not chang
b880: 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c  ed if.** the val
b890: 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f  ue originally po
b8a0: 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61  inted to is nega
b8b0: 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  tive, and so the
b8c0: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a   current limit .
b8d0: 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65  ** can be querie
b8e0: 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20  d by passing in 
b8f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
b900: 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20  egative number. 
b910: 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f   This.** file-co
b920: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e  ntrol is used in
b930: 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c  ternally to impl
b940: 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d  ement [PRAGMA mm
b950: 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20  ap_size]..**.** 
b960: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b970: 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68  TL_TRACE]].** Th
b980: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b990: 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74  TRACE] file cont
b9a0: 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76  rol provides adv
b9b0: 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f  isory informatio
b9c0: 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20  n.** to the VFS 
b9d0: 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68  about what the h
b9e0: 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20  igher layers of 
b9f0: 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b  the SQLite stack
ba00: 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54   are doing..** T
ba10: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
ba20: 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65   is used by some
ba30: 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72   VFS activity tr
ba40: 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a  acing [shims]..*
ba50: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
ba60: 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
ba70: 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67  ted string.  Hig
ba80: 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68  her layers in th
ba90: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63  e.** SQLite stac
baa0: 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69  k may generate i
bab0: 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73  nstances of this
bac0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66   file control if
bad0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
bae0: 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  USE_FCNTL_TRACE]
baf0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
bb00: 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
bb10: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
bb20: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
bb30: 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  VED]].** The [SQ
bb40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
bb50: 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72  OVED] file contr
bb60: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
bb70: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a  s argument as a.
bb80: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
bb90: 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20   integer and it 
bba0: 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e  writes a boolean
bbb0: 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
bbc0: 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  er depending.** 
bbd0: 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  on whether or no
bbe0: 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62  t the file has b
bbf0: 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76  een renamed, mov
bc00: 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73  ed, or deleted s
bc10: 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66  ince it.** was f
bc20: 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  irst opened..**.
bc30: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
bc40: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
bc50: 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20  HANDLE]].** The 
bc60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
bc70: 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20  N32_GET_HANDLE] 
bc80: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73  opcode can be us
bc90: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
bca0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e  .** underlying n
bcb0: 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c  ative file handl
bcc0: 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
bcd0: 68 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e  h a file handle.
bce0: 20 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63    This file.** c
bcf0: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
bd00: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
bd10: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
bd20: 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e   native file han
bd30: 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65  dle and.** write
bd40: 73 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  s the resulting 
bd50: 76 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a  value there..**.
bd60: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
bd70: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
bd80: 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20  HANDLE]].** The 
bd90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
bda0: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20  N32_SET_HANDLE] 
bdb0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
bdc0: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
bdd0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
bde0: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
bdf0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
be00: 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61  swap the file ha
be10: 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e  ndle with the on
be20: 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  e.** pointed to 
be30: 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75  by the pArg argu
be40: 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61  ment.  This capa
be50: 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64  bility is used d
be60: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a  uring testing.**
be70: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
be80: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
be90: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
bea0: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a   is defined..**.
beb0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
bec0: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d  FCNTL_WAL_BLOCK]
bed0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
bee0: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
bef0: 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f  ] is a signal to
bf00: 20 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74   the VFS layer t
bf10: 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20  hat it might.** 
bf20: 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20  be advantageous 
bf30: 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  to block on the 
bf40: 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66  next WAL lock if
bf50: 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74   the lock is not
bf60: 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20   immediately.** 
bf70: 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20  available.  The 
bf80: 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73  WAL subsystem is
bf90: 73 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c  sues this signal
bfa0: 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20   during rare.** 
bfb0: 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e  circumstances in
bfc0: 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20   order to fix a 
bfd0: 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69  problem with pri
bfe0: 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e  ority inversion.
bff0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
c000: 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c   should <em>not<
c010: 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69  /em> use this fi
c020: 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a  le-control..**.*
c030: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c040: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a  CNTL_ZIPVFS]].**
c050: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c060: 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64  TL_ZIPVFS] opcod
c070: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
c080: 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e   by zipvfs only.
c090: 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46   All other.** VF
c0a0: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  S should return 
c0b0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
c0c0: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  for this opcode.
c0d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c0e0: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a  ITE_FCNTL_RBU]].
c0f0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c100: 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65  CNTL_RBU] opcode
c110: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
c120: 62 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  by the special V
c130: 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68  FS used by.** th
c140: 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20  e RBU extension 
c150: 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72  only.  All other
c160: 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75   VFS should retu
c170: 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  rn SQLITE_NOTFOU
c180: 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f  ND for.** this o
c190: 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c  pcode.  .** </ul
c1a0: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
c1b0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
c1c0: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
c1d0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
c1e0: 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43  TE_FCNTL_GET_LOC
c1f0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
c200: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
c210: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
c220: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
c230: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
c240: 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e  _FCNTL_LAST_ERRN
c250: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34  O              4
c260: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c270: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20  FCNTL_SIZE_HINT 
c280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
c290: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c2a0: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20  CNTL_CHUNK_SIZE 
c2b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
c2c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c2d0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
c2e0: 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
c2f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c300: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20  TL_SYNC_OMITTED 
c310: 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65             8.#de
c320: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c330: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
c340: 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
c350: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c360: 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20  _PERSIST_WAL    
c370: 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
c380: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c390: 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20  OVERWRITE       
c3a0: 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e         11.#defin
c3b0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
c3c0: 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  FSNAME          
c3d0: 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65        12.#define
c3e0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f   SQLITE_FCNTL_PO
c3f0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
c400: 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20  E    13.#define 
c410: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
c420: 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
c430: 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53      14.#define S
c440: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
c450: 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20  HANDLER         
c460: 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51     15.#define SQ
c470: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
c480: 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20  ILENAME         
c490: 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
c4a0: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
c4b0: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
c4c0: 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   18.#define SQLI
c4d0: 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20  TE_FCNTL_TRACE  
c4e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c4f0: 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  19.#define SQLIT
c500: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
c510: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  D              2
c520: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
c530: 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20  _FCNTL_SYNC     
c540: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
c550: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c560: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
c570: 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a  SETWO        22.
c580: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c590: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
c5a0: 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23  ANDLE       23.#
c5b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c5c0: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20  NTL_WAL_BLOCK   
c5d0: 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 23 64             24.#d
c5e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c5f0: 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20  TL_ZIPVFS       
c600: 20 20 20 20 20 20 20 20 20 20 32 35 0a 23 64 65            25.#de
c610: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c620: 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20 20 20  L_RBU           
c630: 20 20 20 20 20 20 20 20 20 32 36 0a 23 64 65 66           26.#def
c640: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c650: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20 20  _VFS_POINTER    
c660: 20 20 20 20 20 20 20 20 32 37 0a 23 64 65 66 69          27.#defi
c670: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c680: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20  JOURNAL_POINTER 
c690: 20 20 20 20 20 20 20 32 38 0a 23 64 65 66 69 6e         28.#defin
c6a0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
c6b0: 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 20  IN32_GET_HANDLE 
c6c0: 20 20 20 20 20 20 32 39 0a 23 64 65 66 69 6e 65        29.#define
c6d0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 44   SQLITE_FCNTL_PD
c6e0: 42 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  B               
c6f0: 20 20 20 20 20 33 30 0a 0a 2f 2a 20 64 65 70 72       30../* depr
c700: 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a  ecated names */.
c710: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
c720: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c730: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
c740: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
c750: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c  FILE.#define SQL
c760: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
c770: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54  YFILE      SQLIT
c780: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
c790: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e  PROXYFILE.#defin
c7a0: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
c7b0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
c7c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
c7d0: 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20  T_ERRNO.../*.** 
c7e0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
c7f0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
c800: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
c810: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
c820: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
c830: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
c840: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
c850: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
c860: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
c870: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
c880: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
c890: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
c8a0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
c8b0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
c8c0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
c8d0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
c8e0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
c8f0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
c900: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
c910: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
c920: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
c930: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
c940: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
c950: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
c960: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c970: 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69  Loadable Extensi
c980: 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41  on Thunk.**.** A
c990: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
c9a0: 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61  opaque sqlite3_a
c9b0: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75  pi_routines stru
c9c0: 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64 20  cture is passed 
c9d0: 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20  as.** the third 
c9e0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74  parameter to ent
c9f0: 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f  ry points of [lo
ca00: 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
ca10: 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72  s].  This.** str
ca20: 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 74  ucture must be t
ca30: 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65  ypedefed in orde
ca40: 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  r to work around
ca50: 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e   compiler warnin
ca60: 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c  gs.** on some pl
ca70: 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65  atforms..*/.type
ca80: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
ca90: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
caa0: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
cab0: 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ines;../*.** CAP
cac0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
cad0: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
cae0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
caf0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
cb00: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
cb10: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
cb20: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
cb30: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
cb40: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
cb50: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
cb60: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
cb70: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
cb80: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
cb90: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
cba0: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
cbb0: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
cbc0: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
cbd0: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
cbe0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
cbf0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
cc00: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
cc10: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
cc20: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
cc30: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
cc40: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
cc50: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
cc60: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
cc70: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
cc80: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
cc90: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
cca0: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
ccb0: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
ccc0: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
ccd0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
cce0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
ccf0: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
cd00: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
cd10: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
cd20: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
cd30: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
cd40: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
cd50: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
cd60: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
cd70: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
cd80: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
cd90: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
cda0: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
cdb0: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
cdc0: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
cdd0: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
cde0: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
cdf0: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
ce00: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
ce10: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
ce20: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
ce30: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
ce40: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
ce50: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
ce60: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
ce70: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
ce80: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
ce90: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
cea0: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
ceb0: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
cec0: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
ced0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
cee0: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
cef0: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
cf00: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
cf10: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
cf20: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
cf30: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
cf40: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
cf50: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
cf60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
cf70: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
cf80: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
cf90: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
cfa0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
cfb0: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
cfc0: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
cfd0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
cfe0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
cff0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
d000: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
d010: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
d020: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
d030: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
d040: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
d050: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
d060: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
d070: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
d080: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
d090: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
d0a0: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
d0b0: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
d0c0: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
d0d0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
d0e0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
d0f0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
d100: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
d110: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
d120: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
d130: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
d140: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
d150: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
d160: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
d170: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
d180: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
d190: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
d1a0: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
d1b0: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
d1c0: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
d1d0: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
d1e0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
d1f0: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
d200: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
d210: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
d220: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
d230: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
d240: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
d250: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
d260: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
d270: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
d280: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
d290: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
d2a0: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
d2b0: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
d2c0: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
d2d0: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
d2e0: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
d2f0: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
d300: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
d310: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
d320: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
d330: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
d340: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
d350: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
d360: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
d370: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
d380: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
d390: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
d3a0: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
d3b0: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
d3c0: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
d3d0: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
d3e0: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
d3f0: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
d400: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
d410: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
d420: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
d430: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
d440: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
d450: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
d460: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
d470: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
d480: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
d490: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
d4a0: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
d4b0: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
d4c0: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
d4d0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
d4e0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
d4f0: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
d500: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
d510: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
d520: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
d530: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
d540: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
d550: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
d560: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
d570: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
d580: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
d590: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
d5a0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
d5b0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
d5c0: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
d5d0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
d5e0: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
d5f0: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
d600: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
d610: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
d620: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
d630: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
d640: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
d650: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
d660: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
d670: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
d680: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
d690: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
d6a0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
d6b0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
d6c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
d6d0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
d6e0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
d6f0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
d700: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
d710: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
d720: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d730: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
d740: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d750: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
d760: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d770: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
d780: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
d790: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
d7a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
d7b0: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
d7c0: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
d7d0: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
d7e0: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
d7f0: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
d800: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
d810: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
d820: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
d830: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
d840: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
d850: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
d860: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
d870: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
d880: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
d890: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
d8a0: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
d8b0: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
d8c0: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
d8d0: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
d8e0: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
d8f0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
d900: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
d910: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
d920: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
d930: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
d940: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
d950: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
d960: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
d970: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
d980: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
d990: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
d9a0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
d9b0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
d9c0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
d9d0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
d9e0: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
d9f0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
da00: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
da10: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
da20: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
da30: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
da40: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
da50: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
da60: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
da70: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
da80: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
da90: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
daa0: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
dab0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
dac0: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
dad0: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
dae0: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
daf0: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
db00: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
db10: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
db20: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
db30: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
db40: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
db50: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
db60: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
db70: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
db80: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
db90: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
dba0: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
dbb0: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
dbc0: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
dbd0: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
dbe0: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
dbf0: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
dc00: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
dc10: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
dc20: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
dc30: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
dc40: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
dc50: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
dc60: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
dc70: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
dc80: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
dc90: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
dca0: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
dcb0: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
dcc0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
dcd0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
dce0: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
dcf0: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
dd00: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
dd10: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
dd20: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
dd30: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
dd40: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
dd50: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
dd60: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
dd70: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
dd80: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
dd90: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
dda0: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
ddb0: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
ddc0: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
ddd0: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
dde0: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
ddf0: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
de00: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
de10: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
de20: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
de30: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
de40: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
de50: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
de60: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
de70: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
de80: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
de90: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
dea0: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
deb0: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
dec0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
ded0: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
dee0: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
def0: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
df00: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
df10: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
df20: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
df30: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
df40: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
df50: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
df60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
df70: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
df80: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
df90: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
dfa0: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
dfb0: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
dfc0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
dfd0: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
dfe0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
dff0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
e000: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
e010: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
e020: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
e030: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
e040: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
e050: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
e060: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
e070: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
e080: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
e090: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
e0a0: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
e0b0: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
e0c0: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
e0d0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
e0e0: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
e0f0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
e100: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
e110: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
e120: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
e130: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
e140: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
e150: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
e160: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
e170: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
e180: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
e190: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
e1a0: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
e1b0: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
e1c0: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
e1d0: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
e1e0: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
e1f0: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
e200: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
e210: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
e220: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
e230: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
e240: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
e250: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
e260: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
e270: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
e280: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
e290: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
e2a0: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
e2b0: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
e2c0: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
e2d0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
e2e0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
e2f0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
e300: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
e310: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
e320: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
e330: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
e340: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
e350: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
e360: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
e370: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
e380: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
e390: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
e3a0: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
e3b0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
e3c0: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
e3d0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
e3e0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
e3f0: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
e400: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
e410: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
e420: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
e430: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
e440: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
e450: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
e460: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
e470: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
e480: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
e490: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
e4a0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
e4b0: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
e4c0: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
e4d0: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
e4e0: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
e4f0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
e500: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
e510: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
e520: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
e530: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
e540: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
e550: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
e560: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
e570: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
e580: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
e590: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
e5a0: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
e5b0: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
e5c0: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
e5d0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
e5e0: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
e5f0: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
e600: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
e610: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
e620: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
e630: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
e640: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
e650: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
e660: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
e670: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
e680: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
e690: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
e6a0: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
e6b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
e6c0: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
e6d0: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
e6e0: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
e6f0: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
e700: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
e710: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
e720: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
e730: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
e740: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
e750: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
e760: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
e770: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
e780: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
e790: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
e7a0: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
e7b0: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
e7c0: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
e7d0: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
e7e0: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
e7f0: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
e800: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
e810: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
e820: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
e830: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
e840: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
e850: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
e860: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
e870: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
e880: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
e890: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
e8a0: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
e8b0: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
e8c0: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
e8d0: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
e8e0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
e8f0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
e900: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
e910: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
e920: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
e930: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
e940: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
e950: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
e960: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
e970: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
e980: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
e990: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
e9a0: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
e9b0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
e9c0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
e9d0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
e9e0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
e9f0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
ea00: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
ea10: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
ea20: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
ea30: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
ea40: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
ea50: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
ea60: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
ea70: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
ea80: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
ea90: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
eaa0: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
eab0: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
eac0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
ead0: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
eae0: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
eaf0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
eb00: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
eb10: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
eb20: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
eb30: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
eb40: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
eb50: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
eb60: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
eb70: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
eb80: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
eb90: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
eba0: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
ebb0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
ebc0: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
ebd0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
ebe0: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
ebf0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
ec00: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
ec10: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
ec20: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
ec30: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
ec40: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
ec50: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
ec60: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
ec70: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
ec80: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
ec90: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
eca0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
ecb0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
ecc0: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
ecd0: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
ece0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
ecf0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
ed00: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
ed10: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
ed20: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
ed30: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
ed40: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
ed50: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
ed60: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
ed70: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
ed80: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
ed90: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
eda0: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
edb0: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
edc0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
edd0: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
ede0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
edf0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ee00: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
ee10: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
ee20: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
ee30: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
ee40: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
ee50: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
ee60: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
ee70: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
ee80: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
ee90: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
eea0: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
eeb0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
eec0: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
eed0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
eee0: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
eef0: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
ef00: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
ef10: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
ef20: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
ef30: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
ef40: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
ef50: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
ef60: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
ef70: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
ef80: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
ef90: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
efa0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
efb0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
efc0: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
efd0: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
efe0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
eff0: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
f000: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
f010: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
f020: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
f030: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
f040: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
f050: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
f060: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
f070: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
f080: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
f090: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
f0a0: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
f0b0: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
f0c0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
f0d0: 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65  pended in future
f0e0: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
f0f0: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
f100: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
f110: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
f120: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
f130: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
f140: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
f150: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
f160: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
f170: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
f180: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
f190: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
f1a0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
f1b0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
f1c0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
f1d0: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
f1e0: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
f1f0: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
f200: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
f210: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
f220: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
f230: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
f240: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
f250: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
f260: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
f270: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
f280: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
f290: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
f2a0: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
f2b0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
f2c0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
f2d0: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
f2e0: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
f2f0: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
f300: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
f310: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
f320: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
f330: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
f340: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
f350: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
f360: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f370: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
f380: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
f390: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
f3a0: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
f3b0: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
f3c0: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
f3d0: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
f3e0: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
f3f0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
f400: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
f410: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
f420: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
f430: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
f440: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
f450: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
f460: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
f470: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
f480: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
f490: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
f4a0: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
f4b0: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
f4c0: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
f4d0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
f4e0: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
f4f0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
f500: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
f510: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
f520: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
f530: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
f540: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
f550: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
f560: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
f570: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
f580: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
f590: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
f5a0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
f5b0: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
f5c0: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
f5d0: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
f5e0: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
f5f0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
f600: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
f610: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
f620: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
f630: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
f640: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
f650: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
f660: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
f670: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
f680: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
f690: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
f6a0: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
f6b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
f6c0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
f6d0: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
f6e0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
f6f0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
f700: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
f710: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
f720: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
f730: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
f740: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
f750: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
f760: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
f770: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
f780: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
f790: 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68   was given on th
f7a0: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
f7b0: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
f7c0: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
f7d0: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
f7e0: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
f7f0: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
f800: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
f810: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
f820: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
f830: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
f840: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
f850: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
f860: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
f870: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
f880: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f890: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
f8a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f8b0: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
f8c0: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
f8d0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
f8e0: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
f8f0: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
f900: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
f910: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
f920: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
f930: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
f940: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
f950: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
f960: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
f970: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
f980: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
f990: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
f9a0: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
f9b0: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
f9c0: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
f9d0: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
f9e0: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
f9f0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
fa00: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
fa10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
fa20: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
fa30: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
fa40: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
fa50: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
fa60: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
fa70: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
fa80: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
fa90: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
faa0: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
fab0: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
fac0: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
fad0: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
fae0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
faf0: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
fb00: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
fb10: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
fb20: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
fb30: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
fb40: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
fb50: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
fb60: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
fb70: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
fb80: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
fb90: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
fba0: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
fbb0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
fbc0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
fbd0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
fbe0: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
fbf0: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
fc00: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
fc10: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fc20: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
fc30: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
fc40: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
fc50: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
fc60: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
fc70: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
fc80: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
fc90: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
fca0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
fcb0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
fcc0: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
fcd0: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
fce0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fcf0: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
fd00: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
fd10: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
fd20: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
fd30: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
fd40: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
fd50: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
fd60: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
fd70: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
fd80: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
fd90: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fda0: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
fdb0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fdc0: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
fdd0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
fde0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
fdf0: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
fe00: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
fe10: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
fe20: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
fe30: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fe40: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
fe50: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
fe60: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
fe70: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
fe80: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
fe90: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
fea0: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
feb0: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
fec0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
fed0: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
fee0: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
fef0: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
ff00: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
ff10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ff20: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
ff30: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
ff40: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
ff50: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
ff60: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
ff70: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
ff80: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ff90: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
ffa0: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
ffb0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ffc0: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
ffd0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
ffe0: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
fff0: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
10000 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
10010 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
10020 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
10030 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10040 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
10050 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
10060 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
10070 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
10080 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
10090 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
100a0 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
100b0 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
100c0 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
100d0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
100e0 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
100f0 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
10100 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
10110 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
10120 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
10130 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
10140 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
10150 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
10160 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
10170 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
10180 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
10190 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
101a0 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
101b0 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
101c0 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
101d0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
101e0 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
101f0 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
10200 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
10210 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
10220 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10230 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
10240 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
10250 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
10260 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
10270 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
10280 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
10290 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
102a0 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
102b0 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
102c0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
102d0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
102e0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
102f0 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
10300 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
10310 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
10320 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
10330 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
10340 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
10350 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
10360 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
10370 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10380 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
10390 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
103a0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
103b0 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
103c0 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
103d0 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
103e0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
103f0 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
10400 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
10410 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
10420 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
10430 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
10440 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
10450 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
10460 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
10470 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
10480 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
10490 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
104a0 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
104b0 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
104c0 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
104d0 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
104e0 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
104f0 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
10500 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
10510 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
10520 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
10530 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
10540 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
10550 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
10560 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
10570 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
10580 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
10590 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
105a0 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
105b0 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
105c0 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
105d0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
105e0 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
105f0 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
10600 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
10610 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
10620 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
10630 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
10640 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
10650 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
10660 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
10670 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
10680 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
10690 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
106a0 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
106b0 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
106c0 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
106d0 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
106e0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
106f0 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
10700 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
10710 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
10720 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
10730 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
10740 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
10750 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
10760 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
10770 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
10780 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10790 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
107a0 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
107b0 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
107c0 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
107d0 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
107e0 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
107f0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
10800 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
10810 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10820 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
10830 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
10840 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
10850 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
10860 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
10870 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
10880 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
10890 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
108a0 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
108b0 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
108c0 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
108d0 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
108e0 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
108f0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
10900 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
10910 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
10920 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
10930 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
10940 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
10950 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
10960 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10970 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
10980 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
10990 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
109a0 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
109b0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
109c0 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
109d0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
109e0 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
109f0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
10a00 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
10a10 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
10a20 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
10a30 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
10a40 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
10a50 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49  lize(void);.SQLI
10a60 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
10a70 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
10a80 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
10a90 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
10aa0 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  t(void);.SQLITE_
10ab0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
10ac0 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
10ad0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10ae0 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
10af0 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
10b00 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
10b10 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
10b20 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
10b30 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
10b40 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
10b50 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
10b60 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
10b70 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
10b80 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
10b90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
10ba0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
10bb0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
10bc0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
10bd0 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
10be0 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
10bf0 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
10c00 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
10c10 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
10c20 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
10c30 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
10c40 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
10c50 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  needs..**.** <b>
10c60 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
10c70 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
10c80 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
10c90 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  . The applicatio
10ca0 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
10cb0 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
10cc0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
10cd0 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
10ce0 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
10cf0 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
10d00 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
10d10 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68  ng.</b>.**.** Th
10d20 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
10d30 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
10d40 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
10d50 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
10d60 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
10d70 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
10d80 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10d90 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
10da0 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
10db0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
10dc0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
10dd0 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
10de0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
10df0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
10e00 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
10e10 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
10e20 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
10e30 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
10e40 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
10e50 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
10e60 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
10e70 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
10e80 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
10e90 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
10ea0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
10eb0 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
10ec0 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
10ed0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
10ee0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
10ef0 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
10f00 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67  teger.** [config
10f10 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20  uration option] 
10f20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a  that determines.
10f30 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79  ** what property
10f40 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f   of SQLite is to
10f50 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20   be configured. 
10f60 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
10f70 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65  ments.** vary de
10f80 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b  pending on the [
10f90 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10fa0 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
10fb0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
10fc0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f  **.** ^When a co
10fd0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10fe0 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
10ff0 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
11000 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
11010 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69  .** ^If the opti
11020 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
11030 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
11040 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
11050 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
11060 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
11070 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
11080 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c  or code]..*/.SQL
11090 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
110a0 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
110b0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
110c0 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
110d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
110e0 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
110f0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
11100 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
11110 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
11120 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
11130 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
11140 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
11150 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11160 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
11170 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
11180 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
11190 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
111a0 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
111b0 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
111c0 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
111d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
111e0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
111f0 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
11200 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
11210 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
11220 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
11230 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
11240 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
11250 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
11260 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
11270 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
11280 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
11290 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
112a0 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
112b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
112c0 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
112d0 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
112e0 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
112f0 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
11300 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
11310 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
11320 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
11330 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
11340 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
11350 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
11360 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
11370 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
11380 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
11390 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
113a0 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
113b0 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
113c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
113d0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
113e0 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
113f0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
11400 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
11410 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
11420 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
11430 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
11440 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11450 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
11460 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
11470 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
11480 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
11490 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
114a0 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
114b0 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
114c0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
114d0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
114e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
114f0 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
11500 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11510 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
11520 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
11530 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
11540 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
11550 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
11560 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
11570 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
11580 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
11590 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
115a0 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
115b0 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
115c0 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
115d0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
115e0 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
115f0 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
11600 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11610 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
11620 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
11630 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
11640 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
11650 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
11660 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
11670 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
11680 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
11690 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
116a0 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
116b0 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
116c0 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
116d0 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
116e0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
116f0 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
11700 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
11710 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
11720 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
11730 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
11740 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
11750 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
11760 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
11770 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
11780 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
11790 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
117a0 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
117b0 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
117c0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
117d0 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
117e0 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
117f0 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
11800 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
11810 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
11820 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
11830 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
11840 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
11850 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
11860 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61  loc, xRealloc, a
11870 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
11880 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
11890 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c  the.** malloc(),
118a0 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
118b0 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20  ree() functions 
118c0 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
118d0 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
118e0 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
118f0 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
11900 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
11910 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
11920 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
11930 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
11940 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
11950 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73  p..**.** xSize s
11960 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  hould return the
11970 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
11980 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  of a memory allo
11990 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f  cation.** previo
119a0 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
119b0 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52  om xMalloc or xR
119c0 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c  ealloc.  The all
119d0 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69  ocated size.** i
119e0 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73  s always at leas
119f0 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20  t as big as the 
11a00 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62  requested size b
11a10 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
11a20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75  ..**.** The xRou
11a30 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75  ndup method retu
11a40 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62  rns what would b
11a50 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  e the allocated 
11a60 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d  size of.** a mem
11a70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67  ory allocation g
11a80 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61  iven a particula
11a90 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  r requested size
11aa0 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a  .  Most memory.*
11ab0 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  * allocators rou
11ac0 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c  nd up memory all
11ad0 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73  ocations at leas
11ae0 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75  t to the next mu
11af0 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20  ltiple.** of 8. 
11b00 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73   Some allocators
11b10 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c   round up to a l
11b20 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  arger multiple o
11b30 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20  r to a power of 
11b40 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f  2..** Every memo
11b50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
11b60 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20  quest coming in 
11b70 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33  through [sqlite3
11b80 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72  _malloc()].** or
11b90 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
11ba0 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73  c()] first calls
11bb0 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78   xRoundup.  If x
11bc0 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20  Roundup returns 
11bd0 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73  0, .** that caus
11be0 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  es the correspon
11bf0 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ding memory allo
11c00 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a  cation to fail..
11c10 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20  **.** The xInit 
11c20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a  method initializ
11c30 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
11c40 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78  locator.  For ex
11c50 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
11c60 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
11c70 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
11c80 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
11c90 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
11ca0 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
11cb0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
11cc0 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
11cd0 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
11ce0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11cf0 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
11d00 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
11d10 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
11d20 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
11d30 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
11d40 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
11d50 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
11d60 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
11d70 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
11d80 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
11d90 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
11da0 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
11db0 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
11dc0 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
11dd0 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
11de0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
11df0 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
11e00 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
11e10 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
11e20 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
11e30 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
11e40 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
11e50 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
11e60 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
11e70 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
11e80 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
11e90 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
11ea0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
11eb0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
11ec0 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
11ed0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
11ee0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11ef0 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
11f00 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
11f10 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
11f20 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
11f30 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
11f40 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
11f50 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
11f60 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
11f70 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11f80 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
11f90 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
11fa0 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
11fb0 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
11fc0 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
11fd0 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
11fe0 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
11ff0 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
12000 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
12010 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
12020 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
12030 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
12040 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
12050 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
12060 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
12070 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
12080 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
12090 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
120a0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
120b0 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
120c0 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
120d0 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
120e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
120f0 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
12100 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
12110 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
12120 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
12130 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
12140 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
12150 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
12160 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
12170 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
12180 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
12190 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
121a0 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
121b0 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
121c0 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
121d0 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
121e0 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
121f0 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
12200 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
12210 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
12220 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
12230 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
12240 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
12250 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
12260 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
12270 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
12280 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
12290 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
122a0 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
122b0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
122c0 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
122d0 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
122e0 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
122f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
12300 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
12310 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
12320 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
12330 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
12340 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
12350 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
12360 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
12370 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
12380 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
12390 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
123a0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
123b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
123c0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
123d0 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
123e0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
123f0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
12400 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
12410 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
12420 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
12430 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
12440 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
12450 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
12460 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
12470 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
12480 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
12490 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
124a0 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
124b0 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
124c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
124d0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
124e0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
124f0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
12500 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
12510 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
12520 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
12530 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
12540 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
12550 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
12560 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
12570 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
12580 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
12590 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
125a0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
125b0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
125c0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
125d0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
125e0 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
125f0 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
12600 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
12610 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
12620 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
12630 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
12640 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
12650 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
12660 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
12670 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
12680 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
12690 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
126a0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
126b0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
126c0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
126d0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
126e0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
126f0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
12700 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
12710 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
12720 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
12730 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
12740 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
12750 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
12760 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
12770 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
12780 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
12790 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
127a0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
127b0 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
127c0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
127d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
127e0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
127f0 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
12800 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
12810 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
12820 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
12830 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
12840 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
12850 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
12860 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
12870 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
12880 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
12890 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
128a0 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
128b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
128c0 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
128d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
128e0 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
128f0 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
12900 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
12910 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
12920 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
12930 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
12940 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
12950 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
12960 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
12970 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
12980 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
12990 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
129a0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
129b0 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
129c0 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
129d0 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
129e0 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
129f0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
12a00 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
12a10 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
12a20 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12a30 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
12a40 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12a50 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
12a60 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
12a70 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
12a80 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
12a90 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
12aa0 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
12ab0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12ac0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
12ad0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
12ae0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
12af0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
12b00 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
12b10 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
12b20 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
12b30 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
12b40 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12b50 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
12b60 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
12b70 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12b80 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
12b90 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
12ba0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
12bb0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
12bc0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
12bd0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12be0 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
12bf0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
12c00 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
12c10 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
12c20 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
12c30 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
12c40 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
12c50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
12c60 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
12c70 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
12c80 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
12c90 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
12ca0 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
12cb0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12cc0 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
12cd0 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
12ce0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
12cf0 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
12d00 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
12d10 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
12d20 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
12d30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
12d40 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
12d50 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
12d60 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
12d70 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
12d80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
12d90 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
12da0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
12db0 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
12dc0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
12dd0 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
12de0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
12df0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
12e00 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12e10 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
12e20 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
12e30 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
12e40 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
12e50 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
12e60 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
12e70 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
12e80 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
12e90 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
12ea0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
12eb0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
12ec0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
12ed0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12ee0 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
12ef0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
12f00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12f10 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
12f20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12f30 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
12f40 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
12f50 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74  ONFIG_MALLOC opt
12f60 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
12f70 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
12f80 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  h is .** a point
12f90 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
12fa0 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12fb0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
12fc0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
12fd0 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
12fe0 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
12ff0 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
13000 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
13010 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
13020 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
13030 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
13040 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
13050 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
13060 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
13070 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
13080 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
13090 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
130a0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
130b0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
130c0 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
130d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
130e0 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
130f0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13100 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13110 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
13120 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
13130 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
13140 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
13150 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f  NFIG_GETMALLOC o
13160 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
13170 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
13180 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
13190 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
131a0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
131b0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
131c0 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
131d0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
131e0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
131f0 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
13200 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
13210 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
13220 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
13230 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
13240 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
13250 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
13260 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
13270 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
13280 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
13290 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
132a0 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
132b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
132c0 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
132d0 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
132e0 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
132f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13300 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
13310 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13320 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
13330 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
13340 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
13350 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20  EMSTATUS option 
13360 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
13370 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
13380 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65  t,.** interprete
13390 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20  d as a boolean, 
133a0 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
133b0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
133c0 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d  llection of.** m
133d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
133e0 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57   statistics. ^(W
133f0 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hen memory alloc
13400 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
13410 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
13420 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
13430 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
13440 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65  s become non-ope
13450 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
13460 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
13470 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
13480 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
13490 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
134a0 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
134b0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
134c0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
134d0 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  4()].**   <li> [
134e0 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34  sqlite3_status64
134f0 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
13500 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
13510 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
13520 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
13530 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
13540 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
13550 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
13560 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
13570 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
13580 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
13590 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
135a0 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
135b0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
135c0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
135d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
135e0 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
135f0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
13600 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
13610 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13620 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e  G_SCRATCH option
13630 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
13640 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
13650 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  r.** that SQLite
13660 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72   can use for scr
13670 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28  atch memory.  ^(
13680 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
13690 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20  arguments.** to 
136a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
136b0 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65  RATCH:  A pointe
136c0 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
136d0 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
136e0 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
136f0 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
13700 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
13710 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
13720 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
13730 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
13740 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
13750 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
13760 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
13770 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54  ions (N).)^.** T
13780 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13790 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
137a0 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
137b0 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
137c0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
137d0 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
137e0 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
137f0 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72  will not use mor
13800 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74  e than one scrat
13810 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
13820 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74  hread..** ^SQLit
13830 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
13840 75 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62  uest a scratch b
13850 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
13860 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
13870 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
13880 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  page size..** ^I
13890 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
138a0 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
138b0 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
138c0 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
138d0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
138e0 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
138f0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
13900 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13910 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
13920 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
13930 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e  emory needed.<p>
13940 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70  .** ^When the ap
13950 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64  plication provid
13960 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66  es any amount of
13970 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
13980 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f  using.** SQLITE_
13990 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20  CONFIG_SCRATCH, 
139a0 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e  SQLite avoids un
139b0 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a  necessary large.
139c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
139d0 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69  oc|heap allocati
139e0 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61  ons]..** This ca
139f0 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70  n help [Robson p
13a00 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d  roof|prevent mem
13a10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
13a20 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20  ailures] due to 
13a30 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74  heap.** fragment
13a40 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d  ation in low-mem
13a50 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73  ory embedded sys
13a60 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  tems..** </dd>.*
13a70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13a80 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d  NFIG_PAGECACHE]]
13a90 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13aa0 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
13ab0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
13ac0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
13ad0 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70  ECACHE option sp
13ae0 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79  ecifies a memory
13af0 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51   pool.** that SQ
13b00 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
13b10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
13b20 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68  ge cache with th
13b30 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a  e default page.*
13b40 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
13b50 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  tation.  .** Thi
13b60 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
13b70 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f  option is a no-o
13b80 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  p if an applicat
13b90 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a  ion-define page.
13ba0 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
13bb0 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65  ntation is loade
13bc0 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  d using the [SQL
13bd0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13be0 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61  E2]..** ^There a
13bf0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
13c00 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ts to SQLITE_CON
13c10 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41  FIG_PAGECACHE: A
13c20 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38   pointer to.** 8
13c30 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65  -byte aligned me
13c40 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65  mory (pMem), the
13c50 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
13c60 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73  ge cache line (s
13c70 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e  z),.** and the n
13c80 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c  umber of cache l
13c90 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ines (N)..** The
13ca0 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
13cb0 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
13cc0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
13cd0 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
13ce0 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
13cf0 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
13d00 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65  65536) plus some
13d10 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72   extra bytes for
13d20 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
13d30 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62  ader.  ^The numb
13d40 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65  er of extra byte
13d50 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20  s needed by the 
13d60 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63  page header.** c
13d70 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
13d80 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43   using [SQLITE_C
13d90 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
13da0 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68  SZ]..** ^It is h
13db0 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66  armless, apart f
13dc0 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d  rom the wasted m
13dd0 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68  emory,.** for th
13de0 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74  e sz parameter t
13df0 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  o be larger than
13e00 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65   necessary.  The
13e10 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e   pMem.** argumen
13e20 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
13e30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
13e40 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  or a pointer to 
13e50 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
13e60 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  gned block of me
13e70 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74  mory of at least
13e80 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68   sz*N bytes, oth
13e90 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71  erwise.** subseq
13ea0 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73  uent behavior is
13eb0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
13ec0 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74  When pMem is not
13ed0 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69   NULL, SQLite wi
13ee0 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73 65  ll strive to use
13ef0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
13f00 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73  ided.** to satis
13f10 66 79 20 70 61 67 65 20 63 61 63 68 65 20 6e 65  fy page cache ne
13f20 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63  eds, falling bac
13f30 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  k to [sqlite3_ma
13f40 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20  lloc()] if.** a 
13f50 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20  page cache line 
13f60 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73  is larger than s
13f70 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c  z bytes or if al
13f80 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75  l of the pMem bu
13f90 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75  ffer.** is exhau
13fa0 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65  sted..** ^If pMe
13fb0 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20  m is NULL and N 
13fc0 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  is non-zero, the
13fd0 6e 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  n each database 
13fe0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f  connection.** do
13ff0 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75  es an initial bu
14000 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  lk allocation fo
14010 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
14020 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ory.** from [sql
14030 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73  ite3_malloc()] s
14040 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20  ufficient for N 
14050 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e  cache lines if N
14060 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a   is positive or.
14070 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79  ** of -1024*N by
14080 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61  tes if N is nega
14090 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69  tive, . ^If addi
140a0 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63  tional.** page c
140b0 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e  ache memory is n
140c0 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61  eeded beyond wha
140d0 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
140e0 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20   the initial.** 
140f0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
14100 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
14110 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14120 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f  )] separately fo
14130 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69  r each.** additi
14140 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e  onal cache line.
14150 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14160 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
14170 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  P]] <dt>SQLITE_C
14180 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
14190 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
141a0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
141b0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
141c0 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
141d0 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74   buffer .** that
141e0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
141f0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
14200 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
14210 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a  llocation needs.
14220 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ** beyond those 
14230 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20  provided for by 
14240 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
14250 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b  CRATCH] and.** [
14260 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
14270 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68  GECACHE]..** ^Th
14280 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14290 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f  HEAP option is o
142a0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
142b0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
142c0 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68  led.** with eith
142d0 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
142e0 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53  E_MEMSYS3] or [S
142f0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
14300 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e  SYS5] and return
14310 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  s.** [SQLITE_ERR
14320 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f  OR] if invoked o
14330 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68  therwise..** ^Th
14340 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
14350 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
14360 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a  E_CONFIG_HEAP:.*
14370 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  * An 8-byte alig
14380 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
14390 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
143a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
143b0 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
143c0 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
143d0 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
143e0 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
143f0 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
14400 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
14410 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
14420 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
14430 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
14440 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
14450 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
14460 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
14470 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
14480 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
14490 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
144a0 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
144b0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
144c0 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
144d0 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
144e0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c  NULL then the al
144f0 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
14500 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
14510 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
14520 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
14530 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
14540 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
14550 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
14560 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
14570 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
14580 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
14590 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
145a0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
145b0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
145c0 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
145d0 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
145e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
145f0 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
14600 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
14610 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
14620 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
14630 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
14640 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
14650 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14660 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
14670 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
14680 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
14690 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
146a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
146b0 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  EX option takes 
146c0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
146d0 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20  t which is a.** 
146e0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
146f0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
14700 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
14710 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
14720 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
14730 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72   specifies alter
14740 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
14750 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
14760 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e  to be used.** in
14770 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78   place the mutex
14780 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
14790 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
147a0 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
147b0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
147c0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
147d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
147e0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
147f0 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
14800 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
14810 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
14820 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
14830 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
14840 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
14850 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
14860 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
14870 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14880 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
14890 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
148a0 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
148b0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
148c0 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
148d0 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
148e0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
148f0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
14900 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
14910 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
14920 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
14930 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
14940 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14950 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
14960 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14970 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
14980 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14990 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
149a0 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  ETMUTEX option t
149b0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
149c0 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
149d0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
149e0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
149f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
14a00 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
14a10 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
14a20 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
14a30 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
14a40 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
14a50 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
14a60 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
14a70 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
14a80 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
14a90 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
14aa0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
14ab0 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
14ac0 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
14ad0 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
14ae0 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
14af0 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
14b00 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
14b10 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
14b20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
14b30 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
14b40 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
14b50 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14b60 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
14b70 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
14b80 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
14b90 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
14ba0 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
14bb0 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
14bc0 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
14bd0 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
14be0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
14bf0 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
14c00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14c10 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
14c20 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
14c30 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
14c40 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
14c50 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14c60 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
14c70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14c80 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
14c90 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14ca0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14cb0 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61  KASIDE option ta
14cc0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
14cd0 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
14ce0 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
14cf0 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  size of lookasid
14d00 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68  e memory on each
14d10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
14d20 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66  ction]..** The f
14d30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
14d40 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
14d50 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
14d60 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
14d70 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
14d80 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
14d90 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
14da0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
14db0 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
14dc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14dd0 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20  OKASIDE.** sets 
14de0 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  the <i>default</
14df0 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
14e00 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44  e. The [SQLITE_D
14e10 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
14e20 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20  E].** option to 
14e30 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
14e40 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
14e50 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
14e60 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
14e70 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
14e80 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
14e90 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
14ea0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14eb0 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
14ec0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14ed0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
14ee0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14ef0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
14f00 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14f10 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14f20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
14f30 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
14f40 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
14f50 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
14f60 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
14f70 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74  ifies.** the int
14f80 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74  erface to a cust
14f90 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
14fa0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a  plementation.)^.
14fb0 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ** ^SQLite makes
14fc0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
14fd0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
14fe0 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
14ff0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15000 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15010 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
15020 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15030 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
15040 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
15050 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15060 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  2 option takes a
15070 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
15080 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
15090 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
150a0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
150b0 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
150c0 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
150d0 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20  .** the current 
150e0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
150f0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
15100 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
15110 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15120 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
15130 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15140 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
15150 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
15160 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
15170 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
15180 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
15190 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
151a0 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
151b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
151c0 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
151d0 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
151e0 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
151f0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
15200 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
15210 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
15220 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
15230 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
15240 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
15250 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
15260 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
15270 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
15280 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
15290 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
152a0 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
152b0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
152c0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
152d0 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
152e0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
152f0 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
15300 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
15310 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
15320 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
15330 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
15340 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
15350 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
15360 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
15370 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
15380 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
15390 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
153a0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
153b0 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
153c0 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
153d0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
153e0 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
153f0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
15400 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
15410 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
15420 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
15430 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
15440 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
15450 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
15460 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
15470 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
15480 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
15490 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
154a0 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
154b0 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
154c0 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
154d0 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
154e0 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
154f0 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
15500 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
15510 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
15520 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
15530 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
15540 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
15550 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
15560 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
15570 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
15580 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
15590 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
155a0 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
155b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
155c0 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
155d0 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
155e0 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
155f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15600 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
15610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
15620 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  I.** <dd>^(The S
15630 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
15640 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
15650 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
15660 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20  of type int..** 
15670 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
15680 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
15690 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
156a0 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
156b0 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a  eter is zero,.**
156c0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
156d0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ng is globally d
156e0 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
156f0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
15700 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c  lobally.** enabl
15710 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
15720 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
15730 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
15740 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
15750 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
15760 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
15770 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
15780 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
15790 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
157a0 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
157b0 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
157c0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
157d0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
157e0 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
157f0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
15800 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
15810 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20   is opened. ^If 
15820 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
15830 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
15840 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
15850 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
15860 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
15870 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
15880 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
15890 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
158a0 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
158b0 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55   ^(By default, U
158c0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
158d0 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
158e0 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
158f0 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
15900 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
15910 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
15920 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
15930 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29  symbol defined.)
15940 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
15950 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
15960 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64  _INDEX_SCAN]] <d
15970 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15980 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
15990 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  CAN.** <dd>^The 
159a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
159b0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
159c0 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  N option takes a
159d0 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a   single integer.
159e0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ** argument whic
159f0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
15a00 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e   as a boolean in
15a10 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65   order to enable
15a20 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   or disable.** t
15a30 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
15a40 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
15a50 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20  ull table scans 
15a60 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74  in the query opt
15a70 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  imizer..** ^The 
15a80 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15a90 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
15aa0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
15ab0 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
15ac0 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
15ad0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
15ae0 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
15af0 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
15b00 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
15b10 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
15b20 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
15b30 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
15b40 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
15b50 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
15b60 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
15b70 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
15b80 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
15b90 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
15ba0 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
15bb0 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
15bc0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
15bd0 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
15be0 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
15bf0 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
15c00 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
15c10 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
15c20 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
15c30 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
15c40 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
15c50 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
15c60 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
15c70 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15c80 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
15c90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15ca0 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
15cb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15cc0 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
15cd0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15ce0 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
15cf0 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
15d00 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
15d10 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
15d20 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
15d30 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
15d40 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
15d50 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
15d60 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
15d70 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15d80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
15d90 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
15da0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
15db0 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
15dc0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
15dd0 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
15de0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
15df0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
15e00 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
15e10 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
15e20 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
15e30 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
15e40 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
15e50 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
15e60 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
15e70 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
15e80 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
15e90 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
15ea0 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
15eb0 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
15ec0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
15ed0 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
15ee0 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
15ef0 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
15f00 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
15f10 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
15f20 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
15f30 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
15f40 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
15f50 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
15f60 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
15f70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
15f80 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
15f90 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15fa0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
15fb0 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
15fc0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
15fd0 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
15fe0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
15ff0 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
16000 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
16010 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
16020 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
16030 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
16040 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
16050 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
16060 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
16070 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
16080 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
16090 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
160a0 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
160b0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
160c0 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
160d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
160e0 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
160f0 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
16100 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
16110 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
16120 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
16130 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
16140 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
16150 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
16160 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
16170 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
16180 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
16190 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
161a0 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
161b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
161c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
161d0 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
161e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
161f0 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
16200 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
16210 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
16220 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
16230 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
16240 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
16250 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
16260 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
16270 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
16280 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
16290 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
162a0 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
162b0 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
162c0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
162d0 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
162e0 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
162f0 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
16300 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
16310 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
16320 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
16330 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
16340 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
16350 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
16360 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
16370 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
16380 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
16390 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c  map size.** will
163a0 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75   be silently tru
163b0 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73  ncated if necess
163c0 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64  ary so that it d
163d0 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74  oes not exceed t
163e0 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  he.** compile-ti
163f0 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20  me maximum mmap 
16400 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a  size set by the.
16410 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d  ** [SQLITE_MAX_M
16420 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c  MAP_SIZE] compil
16430 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e  e-time option.)^
16440 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61  .** ^If either a
16450 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
16460 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69  option is negati
16470 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72  ve, then that ar
16480 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61  gument is.** cha
16490 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70  nged to its comp
164a0 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74  ile-time default
164b0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
164c0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
164d0 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  APSIZE]].** <dt>
164e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
164f0 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20  N32_HEAPSIZE.** 
16500 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
16510 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
16520 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20  PSIZE option is 
16530 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
16540 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  f SQLite is.** c
16550 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64  ompiled for Wind
16560 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51  ows with the [SQ
16570 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f  LITE_WIN32_MALLO
16580 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  C] pre-processor
16590 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65   macro.** define
165a0 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  d. ^SQLITE_CONFI
165b0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
165c0 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20   takes a 32-bit 
165d0 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
165e0 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73   value.** that s
165f0 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78  pecifies the max
16600 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65  imum size of the
16610 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a   created heap..*
16620 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16630 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
16640 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  Z]].** <dt>SQLIT
16650 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
16660 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  HDRSZ.** <dd>^Th
16670 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16680 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74  PCACHE_HDRSZ opt
16690 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
166a0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
166b0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
166c0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
166d0 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f   and writes into
166e0 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68   that integer th
166f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
16700 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70  a.** bytes per p
16710 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72  age required for
16720 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53   each page in [S
16730 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
16740 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20  ECACHE]..** The 
16750 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20  amount of extra 
16760 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63  space required c
16770 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64  an change depend
16780 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  ing on the compi
16790 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70  ler,.** target p
167a0 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c  latform, and SQL
167b0 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a  ite version..**.
167c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
167d0 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64  IG_PMASZ]].** <d
167e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
167f0 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  PMASZ.** <dd>^Th
16800 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16810 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b  PMASZ option tak
16820 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
16830 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
16840 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e  s an unsigned in
16850 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74  teger and sets t
16860 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20  he "Minimum PMA 
16870 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75  Size" for the mu
16880 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73  ltithreaded.** s
16890 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e  orter to that in
168a0 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61  teger.  The defa
168b0 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20  ult minimum PMA 
168c0 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74  Size is set by t
168d0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  he.** [SQLITE_SO
168e0 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70  RTER_PMASZ] comp
168f0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
16900 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72    New threads ar
16910 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f  e launched.** to
16920 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20   help with sort 
16930 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20  operations when 
16940 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f  multithreaded so
16950 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62  rting.** is enab
16960 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b  led (using the [
16970 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20  PRAGMA threads] 
16980 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65  command) and the
16990 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65   amount of conte
169a0 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74  nt.** to be sort
169b0 65 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70  ed exceeds the p
169c0 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74  age size times t
169d0 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68  he minimum of th
169e0 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63  e.** [PRAGMA cac
169f0 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67  he_size] setting
16a00 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e   and this value.
16a10 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16a20 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
16a30 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  SPILL]].** <dt>S
16a40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
16a50 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c  TJRNL_SPILL.** <
16a60 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16a70 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
16a80 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65  PILL option take
16a90 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
16aa0 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 62 65  eter which.** be
16ab0 63 6f 6d 65 73 20 74 68 65 20 5b 73 74 61 74 65  comes the [state
16ac0 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70  ment journal] sp
16ad0 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65  ill-to-disk thre
16ae0 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61  shold.  .** [Sta
16af0 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d  tement journals]
16b00 20 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d   are held in mem
16b10 6f 72 79 20 75 6e 74 69 6c 20 74 68 65 69 72 20  ory until their 
16b20 73 69 7a 65 20 28 69 6e 20 62 79 74 65 73 29 0a  size (in bytes).
16b30 2a 2a 20 65 78 63 65 65 64 73 20 74 68 69 73 20  ** exceeds this 
16b40 74 68 72 65 73 68 6f 6c 64 2c 20 61 74 20 77 68  threshold, at wh
16b50 69 63 68 20 70 6f 69 6e 74 20 74 68 65 79 20 61  ich point they a
16b60 72 65 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  re written to di
16b70 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65  sk..** Or if the
16b80 20 74 68 72 65 73 68 6f 6c 64 20 69 73 20 2d 31   threshold is -1
16b90 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72  , statement jour
16ba0 6e 61 6c 73 20 61 72 65 20 61 6c 77 61 79 73 20  nals are always 
16bb0 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76  held.** exclusiv
16bc0 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a  ely in memory..*
16bd0 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20 73 74 61  * Since many sta
16be0 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20  tement journals 
16bf0 6e 65 76 65 72 20 62 65 63 6f 6d 65 20 6c 61 72  never become lar
16c00 67 65 2c 20 73 65 74 74 69 6e 67 20 74 68 65 20  ge, setting the 
16c10 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f  spill.** thresho
16c20 6c 64 20 74 6f 20 61 20 76 61 6c 75 65 20 73 75  ld to a value su
16c30 63 68 20 61 73 20 36 34 4b 69 42 20 63 61 6e 20  ch as 64KiB can 
16c40 67 72 65 61 74 6c 79 20 72 65 64 75 63 65 20 74  greatly reduce t
16c50 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20  he amount of.** 
16c60 49 2f 4f 20 72 65 71 75 69 72 65 64 20 74 6f 20  I/O required to 
16c70 73 75 70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e  support statemen
16c80 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  t rollback..** T
16c90 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
16ca0 20 66 6f 72 20 74 68 69 73 20 73 65 74 74 69 6e   for this settin
16cb0 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  g is controlled 
16cc0 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
16cd0 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  E_STMTJRNL_SPILL
16ce0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
16cf0 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  ption..** </dl>.
16d00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16d10 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
16d20 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
16d30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16d40 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
16d50 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
16d60 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
16d70 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
16d80 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
16d90 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
16da0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
16db0 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
16dc0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
16dd0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
16de0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16df0 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
16e00 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
16e10 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
16e20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16e30 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
16e40 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
16e50 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
16e60 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16e70 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
16e80 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
16e90 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
16ea0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16eb0 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
16ec0 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
16ed0 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
16ee0 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
16ef0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
16f00 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
16f10 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
16f20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16f30 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
16f40 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
16f50 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
16f60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16f70 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
16f80 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
16f90 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
16fa0 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
16fb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
16fc0 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
16fd0 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
16fe0 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
16ff0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
17000 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
17010 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
17020 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17030 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
17040 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
17050 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17060 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
17070 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  15  /* no-op */.
17080 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17090 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
170a0 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
170b0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
170c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
170d0 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20  URI          17 
170e0 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
170f0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17100 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38  _PCACHE2      18
17110 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
17120 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
17130 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17140 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
17150 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74  2   19  /* sqlit
17160 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
17170 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
17180 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
17190 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
171a0 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   20  /* int */.#
171b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
171c0 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20  NFIG_SQLLOG     
171d0 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67    21  /* xSqllog
171e0 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
171f0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17200 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32  _MMAP_SIZE    22
17210 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74    /* sqlite3_int
17220 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  64, sqlite3_int6
17230 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  4 */.#define SQL
17240 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
17250 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32  _HEAPSIZE      2
17260 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  3  /* int nByte 
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 43 41 43 48 45 5f  E_CONFIG_PCACHE_
17290 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20  HDRSZ        24 
172a0 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a   /* int *psz */.
172b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
172c0 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20  ONFIG_PMASZ     
172d0 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a            25  /*
172e0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a   unsigned int sz
172f0 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  Pma */.#define S
17300 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
17310 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20  TJRNL_SPILL     
17320 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74   26  /* int nByt
17330 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e */../*.** CAPI
17340 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
17350 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
17360 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
17370 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
17380 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
17390 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
173a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
173b0 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
173c0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
173d0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
173e0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
173f0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
17400 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
17410 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
17420 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
17430 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
17440 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
17450 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
17460 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
17470 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
17480 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
17490 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
174a0 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
174b0 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
174c0 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
174d0 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
174e0 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
174f0 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
17500 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
17510 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
17520 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
17530 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
17540 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
17550 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
17560 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
17570 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17580 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
17590 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
175a0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
175b0 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
175c0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
175d0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
175e0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
175f0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
17600 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
17610 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
17620 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
17630 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
17640 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17650 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
17660 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
17670 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
17680 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
17690 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
176a0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
176b0 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
176c0 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
176d0 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
176e0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
176f0 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
17700 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
17710 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
17720 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
17730 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
17740 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
17750 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
17760 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
17770 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
17780 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
17790 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
177a0 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
177b0 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
177c0 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
177d0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
177e0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
177f0 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
17800 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
17810 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
17820 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
17830 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
17840 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
17850 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
17860 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
17870 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
17880 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
17890 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
178a0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
178b0 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
178c0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
178d0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
178e0 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
178f0 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
17900 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
17910 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
17920 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
17930 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
17940 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
17950 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
17960 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
17970 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
17980 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
17990 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
179a0 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
179b0 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
179c0 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
179d0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
179e0 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
179f0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
17a00 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
17a10 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
17a20 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
17a30 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
17a40 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
17a50 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
17a60 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
17a70 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
17a80 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
17a90 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
17aa0 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
17ab0 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
17ac0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
17ad0 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
17ae0 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
17af0 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
17b00 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
17b10 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
17b20 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
17b30 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
17b40 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
17b50 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
17b60 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
17b70 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
17b80 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
17b90 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
17ba0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
17bb0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
17bc0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17bd0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
17be0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
17bf0 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
17c00 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
17c10 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
17c20 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
17c30 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
17c40 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
17c50 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
17c60 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17c70 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
17c80 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
17c90 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
17ca0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
17cb0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
17cc0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
17cd0 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
17ce0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
17cf0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
17d00 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
17d10 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
17d20 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
17d30 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
17d40 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
17d50 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
17d60 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
17d70 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
17d80 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
17d90 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
17da0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
17db0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
17dc0 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
17dd0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
17de0 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
17df0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
17e00 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
17e10 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
17e20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
17e30 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
17e40 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
17e50 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
17e60 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
17e70 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
17e80 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
17e90 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
17ea0 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
17eb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
17ec0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
17ed0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
17ee0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
17ef0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
17f00 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
17f10 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
17f20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
17f30 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
17f40 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
17f50 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
17f60 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
17f70 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
17f80 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
17f90 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
17fa0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
17fb0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
17fc0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
17fd0 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52  E_FTS3_TOKENIZER
17fe0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
17ff0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
18000 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
18010 64 69 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d  disable the two-
18020 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73  argument.** vers
18030 69 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33  ion of the [fts3
18040 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75  _tokenizer()] fu
18050 6e 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20  nction which is 
18060 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  part of the.** [
18070 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20  FTS3] full-text 
18080 73 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78  search engine ex
18090 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72  tension..** Ther
180a0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
180b0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
180c0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
180d0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
180e0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
180f0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
18100 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
18110 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20   or.** positive 
18120 74 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74  to enable fts3_t
18130 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65  okenizer() or ne
18140 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
18150 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75  the setting.** u
18160 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
18170 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18180 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
18190 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
181a0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
181b0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
181c0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
181d0 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20   fts3_tokenizer 
181e0 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
181f0 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
18200 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
18210 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
18220 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
18230 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
18240 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
18250 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20   new setting is 
18260 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
18270 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
18280 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
18290 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45  IG_ENABLE_LOAD_E
182a0 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a  XTENSION</dt>.**
182b0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
182c0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
182d0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
182e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  the [sqlite3_loa
182f0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a  d_extension()].*
18300 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65  * interface inde
18310 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65  pendently of the
18320 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e   [load_extension
18330 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ()] SQL function
18340 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
18350 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
18360 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65  tension()] API e
18370 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
18380 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43  es both the.** C
18390 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  -API [sqlite3_lo
183a0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
183b0 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
183c0 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e  tion [load_exten
183d0 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72  sion()]..** Ther
183e0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
183f0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
18400 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  ents..** When th
18410 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18420 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61   to this interfa
18430 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e  ce is 1, then on
18440 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a  ly the C-API is.
18450 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74  ** enabled and t
18460 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
18470 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64  remains disabled
18480 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20  .  If the first 
18490 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
184a0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
184b0 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68   0, then both th
184c0 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20  e C-API and the 
184d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  SQL function are
184e0 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66   disabled..** If
184f0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
18500 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ent is -1, then 
18510 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d  no changes are m
18520 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20  ade to state of 
18530 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d  either the.** C-
18540 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66  API or the SQL f
18550 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20  unction..** The 
18560 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18570 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
18580 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
18590 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
185a0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
185b0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
185c0 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
185d0 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72  tension()] inter
185e0 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62  face.** is disab
185f0 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66  led or enabled f
18600 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
18610 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
18620 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a  parameter may.**
18630 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
18640 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  er, in which cas
18650 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e  e the new settin
18660 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
18670 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e  d back..** </dd>
18680 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
18690 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44  E_DBCONFIG_MAIND
186a0 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BNAME</dt>.** <d
186b0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
186c0 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  is used to chang
186d0 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  e the name of th
186e0 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73  e "main" databas
186f0 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54  e.** schema.  ^T
18700 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74  he sole argument
18710 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
18720 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38   a constant UTF8
18730 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68   string.** which
18740 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
18750 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65   new schema name
18760 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61   in place of "ma
18770 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a  in".  ^SQLite.**
18780 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61   does not make a
18790 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77   copy of the new
187a0 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d   main schema nam
187b0 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65  e string, so the
187c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
187d0 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74  must ensure that
187e0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61   the argument pa
187f0 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44  ssed into this D
18800 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69  BCONFIG option i
18810 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75  s unchanged.** u
18820 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 20 64  ntil after the d
18830 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18840 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f  on closes..** </
18850 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
18860 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f  LITE_DBCONFIG_NO
18870 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f  _CKPT_ON_CLOSE</
18880 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61  dt>.** <dd> Usua
18890 6c 6c 79 2c 20 77 68 65 6e 20 61 20 64 61 74 61  lly, when a data
188a0 62 61 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65  base in wal mode
188b0 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 64 65   is closed or de
188c0 74 61 63 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a  tached from a .*
188d0 2a 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * database handl
188e0 65 2c 20 53 51 4c 69 74 65 20 63 68 65 63 6b 73  e, SQLite checks
188f0 20 69 66 20 74 68 69 73 20 77 69 6c 6c 20 6d 65   if this will me
18900 61 6e 20 74 68 61 74 20 74 68 65 72 65 20 61 72  an that there ar
18910 65 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e  e now no .** con
18920 6e 65 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20  nections at all 
18930 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  to the database.
18940 20 49 66 20 73 6f 2c 20 69 74 20 70 65 72 66 6f   If so, it perfo
18950 72 6d 73 20 61 20 63 68 65 63 6b 70 6f 69 6e 74  rms a checkpoint
18960 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62   .** operation b
18970 65 66 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74 68  efore closing th
18980 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68  e connection. Th
18990 69 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65  is option may be
189a0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72   used to.** over
189b0 72 69 64 65 20 74 68 69 73 20 62 65 68 61 76 69  ride this behavi
189c0 6f 75 72 2e 20 54 68 65 20 66 69 72 73 74 20 70  our. The first p
189d0 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
189e0 74 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f  to this operatio
189f0 6e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67  n.** is an integ
18a00 65 72 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f  er - non-zero to
18a10 20 64 69 73 61 62 6c 65 20 63 68 65 63 6b 70 6f   disable checkpo
18a20 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f  ints-on-close, o
18a30 72 20 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64  r zero (the.** d
18a40 65 66 61 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c  efault) to enabl
18a50 65 20 74 68 65 6d 2e 20 54 68 65 20 73 65 63 6f  e them. The seco
18a60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
18a70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
18a80 69 6e 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20  integer.** into 
18a90 77 68 69 63 68 20 69 73 20 77 72 69 74 74 65 6e  which is written
18aa0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
18ab0 61 74 65 20 77 68 65 74 68 65 72 20 63 68 65 63  ate whether chec
18ac0 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65  kpoints-on-close
18ad0 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 64 69  .** have been di
18ae0 73 61 62 6c 65 64 20 2d 20 30 20 69 66 20 74 68  sabled - 0 if th
18af0 65 79 20 61 72 65 20 6e 6f 74 20 64 69 73 61 62  ey are not disab
18b00 6c 65 64 2c 20 31 20 69 66 20 74 68 65 79 20 61  led, 1 if they a
18b10 72 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  re..** </dd>.**.
18b20 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
18b30 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
18b40 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20  FIG_MAINDBNAME  
18b50 20 20 20 20 20 20 20 20 20 20 31 30 30 30 20 2f            1000 /
18b60 2a 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f  * const char* */
18b70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18b80 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
18b90 44 45 20 20 20 20 20 20 20 20 20 20 20 20 20 31  DE             1
18ba0 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  001 /* void* int
18bb0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
18bc0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18bd0 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
18be0 20 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e        1002 /* in
18bf0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
18c00 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
18c10 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
18c20 20 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20          1003 /* 
18c30 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
18c40 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
18c50 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f  FIG_ENABLE_FTS3_
18c60 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f  TOKENIZER 1004 /
18c70 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
18c80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
18c90 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41  ONFIG_ENABLE_LOA
18ca0 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 35  D_EXTENSION 1005
18cb0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
18cc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18cd0 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
18ce0 4f 4e 5f 43 4c 4f 53 45 20 20 20 20 20 20 31 30  ON_CLOSE      10
18cf0 30 36 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  06 /* int int* *
18d00 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
18d10 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
18d20 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
18d30 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d  esult Codes.** M
18d40 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
18d50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
18d60 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
18d70 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e  t_codes() routin
18d80 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
18d90 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78  ables the.** [ex
18da0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
18db0 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20  des] feature of 
18dc0 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74  SQLite. ^The ext
18dd0 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
18de0 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
18df0 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
18e00 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
18e10 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53  patibility..*/.S
18e20 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
18e30 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
18e40 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
18e50 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
18e60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18e70 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
18e80 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  owid.** METHOD: 
18e90 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45  sqlite3.**.** ^E
18ea0 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73  ach entry in mos
18eb0 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20  t SQLite tables 
18ec0 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54  (except for [WIT
18ed0 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
18ee0 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69  es).** has a uni
18ef0 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
18f00 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
18f10 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57   called the [ROW
18f20 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e  ID | "rowid"]. ^
18f30 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77  The rowid is alw
18f40 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a  ays available.**
18f50 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
18f60 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52  d column named R
18f70 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
18f80 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73  OWID_ as long as
18f90 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20   those.** names 
18fa0 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65  are not also use
18fb0 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20  d by explicitly 
18fc0 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
18fd0 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62  . ^If.** the tab
18fe0 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
18ff0 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52  of type [INTEGER
19000 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68   PRIMARY KEY] th
19010 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a  en that column.*
19020 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69  * is another ali
19030 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64  as for the rowid
19040 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
19050 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
19060 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66  _rowid(D) interf
19070 61 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75  ace usually retu
19080 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  rns the [rowid] 
19090 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72  of.** the most r
190a0 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c  ecent successful
190b0 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61   [INSERT] into a
190c0 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20   rowid table or 
190d0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
190e0 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63  ** on database c
190f0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e  onnection D. ^In
19100 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48  serts into [WITH
19110 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
19120 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63  s are not.** rec
19130 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75  orded. ^If no su
19140 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
19150 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61  ]s into rowid ta
19160 62 6c 65 73 20 68 61 76 65 20 65 76 65 72 20 6f  bles have ever o
19170 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74  ccurred .** on t
19180 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
19190 65 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73  ection D, then s
191a0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
191b0 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75  rt_rowid(D) retu
191c0 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a  rns .** zero..**
191d0 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62  .** As well as b
191e0 65 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74  eing set automat
191f0 69 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61  ically as rows a
19200 72 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  re inserted into
19210 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62   database.** tab
19220 6c 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  les, the value r
19230 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
19240 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
19250 73 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62  set explicitly b
19260 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  y.** [sqlite3_se
19270 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  t_last_insert_ro
19280 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d  wid()].**.** Som
19290 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
192a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
192b0 6d 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20  may INSERT rows 
192c0 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
192d0 73 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  s as.** part of 
192e0 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61  committing a tra
192f0 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74  nsaction (e.g. t
19300 6f 20 66 6c 75 73 68 20 64 61 74 61 20 61 63 63  o flush data acc
19310 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f  umulated in memo
19320 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20  ry.** to disk). 
19330 49 6e 20 74 68 69 73 20 63 61 73 65 20 73 75 62  In this case sub
19340 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
19350 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
19360 65 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a  eturn the rowid.
19370 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
19380 74 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61  th these interna
19390 6c 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69  l INSERT operati
193a0 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73  ons, which leads
193b0 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74   to .** unintuit
193c0 69 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72  ive results. Vir
193d0 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
193e0 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20  mentations that 
193f0 64 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69  do write to rowi
19400 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74  d.** tables in t
19410 68 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69  his way can avoi
19420 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62  d this problem b
19430 79 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20  y restoring the 
19440 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77  original .** row
19450 69 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b  id value using [
19460 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
19470 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
19480 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
19490 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f  g .** control to
194a0 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a   the user..**.**
194b0 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54   ^(If an [INSERT
194c0 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  ] occurs within 
194d0 61 20 74 72 69 67 67 65 72 20 74 68 65 6e 20 74  a trigger then t
194e0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
194f0 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20   .** return the 
19500 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
19510 6e 73 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c  nserted row as l
19520 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
19530 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e  er is .** runnin
19540 67 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67  g. Once the trig
19550 67 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73  ger program ends
19560 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
19570 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73  rned .** by this
19580 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
19590 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
195a0 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
195b0 65 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a  er was fired.)^.
195c0 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
195d0 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
195e0 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
195f0 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
19600 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
19610 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
19620 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
19630 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
19640 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
19650 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
19660 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
19670 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
19680 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
19690 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
196a0 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
196b0 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
196c0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
196d0 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
196e0 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
196f0 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
19700 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
19710 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
19720 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
19730 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
19740 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
19750 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
19760 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
19770 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
19780 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
19790 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
197a0 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
197b0 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
197c0 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
197d0 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
197e0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
197f0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
19800 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
19810 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
19820 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
19830 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
19840 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
19850 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
19860 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
19870 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
19880 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
19890 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
198a0 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
198b0 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
198c0 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
198d0 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
198e0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
198f0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
19900 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
19910 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
19920 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
19930 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
19940 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
19950 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
19960 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
19970 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
19980 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
19990 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
199a0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
199b0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
199c0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
199d0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
199e0 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
199f0 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
19a00 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
19a10 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
19a20 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
19a30 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49  [rowid]..*/.SQLI
19a40 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
19a50 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
19a60 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
19a70 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
19a80 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 74   CAPI3REF: Set t
19a90 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  he Last Insert R
19aa0 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d  owid value..** M
19ab0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
19ac0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
19ad0 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74  _set_last_insert
19ae0 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 74  _rowid(D, R) met
19af0 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 61  hod allows the a
19b00 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
19b10 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 72   set the value r
19b20 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c 69  eturned by calli
19b30 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  ng sqlite3_last_
19b40 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
19b50 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74  to R .** without
19b60 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f 77   inserting a row
19b70 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
19b80 73 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  se..*/.SQLITE_AP
19b90 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  I void sqlite3_s
19ba0 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  et_last_insert_r
19bb0 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 2c 73 71  owid(sqlite3*,sq
19bc0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f  lite3_int64);../
19bd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
19be0 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
19bf0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
19c00 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
19c10 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
19c20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
19c30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
19c40 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e  ows modified, in
19c50 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  serted or.** del
19c60 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
19c70 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
19c80 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
19c90 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  TE or DELETE.** 
19ca0 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65  statement on the
19cb0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19cc0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62  tion specified b
19cd0 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  y the only param
19ce0 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74  eter..** ^Execut
19cf0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
19d00 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
19d10 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64  ent does not mod
19d20 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  ify the value.**
19d30 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
19d40 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
19d50 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  * ^Only changes 
19d60 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 62 79  made directly by
19d70 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44   the INSERT, UPD
19d80 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
19d90 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63  atement are.** c
19da0 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78 69  onsidered - auxi
19db0 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
19dc0 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 45 20  used by [CREATE 
19dd0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
19de0 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67  rs], .** [foreig
19df0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f  n key actions] o
19e00 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  r [REPLACE] cons
19e10 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
19e20 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  n are not counte
19e30 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65  d..** .** Change
19e40 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
19e50 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
19e60 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44   by .** [INSTEAD
19e70 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e   OF trigger | IN
19e80 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
19e90 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
19ea0 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a  ed. ^The value .
19eb0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
19ec0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
19ed0 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74   immediately aft
19ee0 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  er an INSERT, UP
19ef0 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45  DATE or .** DELE
19f00 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e  TE statement run
19f10 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c   on a view is al
19f20 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20  ways zero. Only 
19f30 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20  changes made to 
19f40 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20  real .** tables 
19f50 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
19f60 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f  ** Things are mo
19f70 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69  re complicated i
19f80 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  f the sqlite3_ch
19f90 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
19fa0 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   is.** executed 
19fb0 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 72 20  while a trigger 
19fc0 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69  program is runni
19fd0 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70  ng. This may hap
19fe0 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72  pen if the.** pr
19ff0 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b  ogram uses the [
1a000 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1a010 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73  nction], or if s
1a020 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61  ome other callba
1a030 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  ck.** function i
1a040 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63  nvokes sqlite3_c
1a050 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c  hanges() directl
1a060 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a  y. Essentially:.
1a070 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  ** .** <ul>.**  
1a080 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65   <li> ^(Before e
1a090 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 67 65  ntering a trigge
1a0a0 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61  r program the va
1a0b0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a  lue returned by.
1a0c0 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74 65  **        sqlite
1a0d0 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  3_changes() func
1a0e0 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41  tion is saved. A
1a0f0 66 74 65 72 20 74 68 65 20 74 72 69 67 67 65 72  fter the trigger
1a100 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20   program .**    
1a110 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 65 64      has finished
1a120 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76  , the original v
1a130 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65 64  alue is restored
1a140 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69  .)^.** .**   <li
1a150 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69  > ^(Within a tri
1a160 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63  gger program eac
1a170 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  h INSERT, UPDATE
1a180 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20   and DELETE .** 
1a190 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
1a1a0 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 65 20   sets the value 
1a1b0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1a1c0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a  te3_changes() .*
1a1d0 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f  *        upon co
1a1e0 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d  mpletion as norm
1a1f0 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74  al. Of course, t
1a200 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e  his value will n
1a210 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20  ot include .**  
1a220 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65        any change
1a230 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73  s performed by s
1a240 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20  ub-triggers, as 
1a250 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
1a260 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ges() .**       
1a270 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73   value will be s
1a280 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65  aved and restore
1a290 64 20 61 66 74 65 72 20 65 61 63 68 20 73 75 62  d after each sub
1a2a0 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 75 6e  -trigger has run
1a2b0 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  .)^.** </ul>.** 
1a2c0 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20  .** ^This means 
1a2d0 74 68 61 74 20 69 66 20 74 68 65 20 63 68 61 6e  that if the chan
1a2e0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1a2f0 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20  on (or similar) 
1a300 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68  is used.** by th
1a310 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20  e first INSERT, 
1a320 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
1a330 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
1a340 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 74 20  n a trigger, it 
1a350 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
1a360 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 68 65  value as set whe
1a370 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74  n the calling st
1a380 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78  atement began ex
1a390 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20  ecuting..** ^If 
1a3a0 69 74 20 69 73 20 75 73 65 64 20 62 79 20 74 68  it is used by th
1a3b0 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73  e second or subs
1a3c0 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 61 74  equent such stat
1a3d0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74  ement within a t
1a3e0 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72  rigger .** progr
1a3f0 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  am, the value re
1a400 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20  turned reflects 
1a410 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
1a420 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74  ws modified by t
1a430 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  he .** previous 
1a440 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1a450 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
1a460 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
1a470 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a  me trigger..**.*
1a480 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
1a490 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1a4a0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
1a4b0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
1a4c0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
1a4d0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e  ], and the [chan
1a4e0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1a4f0 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
1a500 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1a510 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
1a520 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
1a530 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1a540 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
1a550 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
1a560 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
1a570 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
1a580 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
1a590 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
1a5a0 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  gful..*/.SQLITE_
1a5b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1a5c0 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
1a5d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a5e0 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
1a5f0 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
1a600 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
1a610 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1a620 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1a630 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  s the total numb
1a640 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72  er of rows inser
1a650 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72  ted, modified or
1a660 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61  .** deleted by a
1a670 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50  ll [INSERT], [UP
1a680 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
1a690 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d  ] statements com
1a6a0 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20  pleted.** since 
1a6b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1a6c0 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e  nection was open
1a6d0 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  ed, including th
1a6e0 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a  ose executed as.
1a6f0 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67  ** part of trigg
1a700 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78  er programs. ^Ex
1a710 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65  ecuting any othe
1a720 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74  r type of SQL st
1a730 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20  atement.** does 
1a740 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76  not affect the v
1a750 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1a760 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
1a770 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a  hanges()..** .**
1a780 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61   ^Changes made a
1a790 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69  s part of [forei
1a7a0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
1a7b0 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  are included in 
1a7c0 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75  the.** count, bu
1a7d0 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20  t those made as 
1a7e0 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20  part of REPLACE 
1a7f0 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
1a800 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74  ution are.** not
1a810 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20  . ^Changes to a 
1a820 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
1a830 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53  tercepted by INS
1a840 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73  TEAD OF triggers
1a850 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75   .** are not cou
1a860 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65  nted..** .** See
1a870 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
1a880 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
1a890 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
1a8a0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
1a8b0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
1a8c0 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  [total_changes()
1a8d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
1a8e0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
1a8f0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
1a900 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
1a910 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
1a920 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
1a930 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
1a940 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
1a950 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
1a960 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
1a970 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
1a980 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
1a990 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ngful..*/.SQLITE
1a9a0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1a9b0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
1a9c0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1a9d0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
1a9e0 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
1a9f0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54  ing Query.** MET
1aa00 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1aa10 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1aa20 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
1aa30 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
1aa40 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
1aa50 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
1aa60 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
1aa70 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
1aa80 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
1aa90 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
1aaa0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
1aab0 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
1aac0 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
1aad0 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
1aae0 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
1aaf0 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
1ab00 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
1ab10 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
1ab20 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
1ab30 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
1ab40 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
1ab50 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
1ab60 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
1ab70 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
1ab80 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
1ab90 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
1aba0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
1abb0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
1abc0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
1abd0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
1abe0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1abf0 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
1ac00 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
1ac10 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
1ac20 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1ac30 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1ac40 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
1ac50 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
1ac60 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
1ac70 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
1ac80 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1ac90 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
1aca0 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
1acb0 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
1acc0 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
1acd0 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
1ace0 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
1acf0 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
1ad00 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
1ad10 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
1ad20 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
1ad30 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
1ad40 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
1ad50 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
1ad60 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
1ad70 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
1ad80 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
1ad90 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
1ada0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
1adb0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
1adc0 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
1add0 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
1ade0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
1adf0 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
1ae00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
1ae10 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
1ae20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
1ae30 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
1ae40 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1ae50 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
1ae60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ae70 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
1ae80 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
1ae90 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1aea0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1aeb0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1aec0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1aed0 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
1aee0 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
1aef0 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
1af00 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
1af10 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
1af20 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
1af30 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
1af40 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1af50 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
1af60 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1af70 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1af80 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
1af90 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
1afa0 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
1afb0 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
1afc0 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
1afd0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
1afe0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
1aff0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1b000 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
1b010 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
1b020 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
1b030 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
1b040 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
1b050 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
1b060 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1b070 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1b080 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
1b090 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1b0a0 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 53 51  l returns..*/.SQ
1b0b0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
1b0c0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1b0d0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1b0e0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
1b0f0 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
1b100 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
1b110 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
1b120 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
1b130 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d  seful during com
1b140 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
1b150 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
1b160 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
1b170 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
1b180 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f  ems to form a co
1b190 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
1b1a0 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
1b1b0 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
1b1c0 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
1b1d0 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
1b1e0 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
1b1f0 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54  for parsing.  ^T
1b200 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1b210 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e  turn 1 if the in
1b220 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
1b230 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
1b240 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
1b250 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d  ment.  ^A statem
1b260 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f  ent is judged to
1b270 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20   be.** complete 
1b280 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20  if it ends with 
1b290 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65  a semicolon toke
1b2a0 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  n and is not a p
1b2b0 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65  refix of a.** we
1b2c0 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45  ll-formed CREATE
1b2d0 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
1b2e0 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73  nt.  ^Semicolons
1b2f0 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
1b300 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
1b310 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
1b320 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
1b330 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
1b340 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
1b350 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
1b360 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
1b370 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
1b380 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
1b390 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
1b3a0 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
1b3b0 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
1b3c0 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  t terminator.  ^
1b3d0 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
1b3e0 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
1b3f0 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
1b400 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
1b410 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gnored..**.** ^T
1b420 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1b430 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74  turn 0 if the st
1b440 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d  atement is incom
1b450 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a  plete.  ^If a.**
1b460 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1b470 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53  on fails, then S
1b480 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72  QLITE_NOMEM is r
1b490 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
1b4a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
1b4b0 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
1b4c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
1b4d0 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
1b4e0 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
1b4f0 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
1b500 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53  QL..**.** ^(If S
1b510 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65  QLite has not be
1b520 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  en initialized u
1b530 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e  sing [sqlite3_in
1b540 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f  itialize()] prio
1b550 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e  r .** to invokin
1b560 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  g sqlite3_comple
1b570 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69  te16() then sqli
1b580 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1b590 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
1b5a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
1b5b0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b5c0 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69  16().  If that i
1b5d0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61  nitialization fa
1b5e0 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ils,.** then the
1b5f0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1b600 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  om sqlite3_compl
1b610 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20  ete16() will be 
1b620 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61  non-zero.** rega
1b630 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
1b640 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70  r or not the inp
1b650 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65  ut SQL is comple
1b660 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.)^.**.** The 
1b670 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1b680 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75  3_complete()] mu
1b690 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1b6a0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38  minated.** UTF-8
1b6b0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
1b6c0 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
1b6d0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1b6e0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1b6f0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1b700 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
1b710 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1b720 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  er..*/.SQLITE_AP
1b730 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
1b740 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
1b750 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f  r *sql);.SQLITE_
1b760 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1b770 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
1b780 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
1b790 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1b7a0 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
1b7b0 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
1b7c0 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
1b7d0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73  * KEYWORDS: {bus
1b7e0 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
1b7f0 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65  ck} {busy handle
1b800 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
1b810 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1b820 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1b830 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75  ndler(D,X,P) rou
1b840 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
1b850 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a  back function X.
1b860 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  ** that might be
1b870 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
1b880 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
1b890 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
1b8a0 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1b8b0 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  s a database tab
1b8c0 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
1b8d0 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  th.** [database 
1b8e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68  connection] D wh
1b8f0 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  en another threa
1b900 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
1b910 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f  has the table lo
1b920 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cked..** The sql
1b930 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1b940 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  r() interface is
1b950 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1b960 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nt.** [sqlite3_b
1b970 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61  usy_timeout()] a
1b980 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  nd [PRAGMA busy_
1b990 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20  timeout]..**.** 
1b9a0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1b9b0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
1b9c0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
1b9d0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
1b9e0 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
1b9f0 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
1ba00 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
1ba10 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
1ba20 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
1ba30 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
1ba40 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
1ba50 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
1ba60 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1ba70 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1ba80 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
1ba90 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
1baa0 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
1bab0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
1bac0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
1bad0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
1bae0 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
1baf0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1bb00 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
1bb10 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
1bb20 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
1bb30 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
1bb40 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1bb50 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
1bb60 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20  oked previously 
1bb70 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
1bb80 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
1bb90 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
1bba0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
1bbb0 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
1bbc0 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
1bbd0 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
1bbe0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1bbf0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
1bc00 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ] is returned.**
1bc10 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1bc20 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
1bc30 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1bc40 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
1bc50 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
1bc60 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  ** is made to ac
1bc70 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1bc80 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  e and the cycle 
1bc90 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
1bca0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
1bcb0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
1bcc0 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
1bcd0 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
1bce0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
1bcf0 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
1bd00 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
1bd10 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
1bd20 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
1bd30 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
1bd40 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
1bd50 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
1bd60 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
1bd70 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
1bd80 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74  TE_BUSY].** to t
1bd90 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1bda0 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
1bdb0 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20  ng the .** busy 
1bdc0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
1bdd0 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
1bde0 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
1bdf0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1be00 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
1be10 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
1be20 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
1be30 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
1be40 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
1be50 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1be60 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
1be70 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
1be80 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
1be90 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
1bea0 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
1beb0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
1bec0 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
1bed0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1bee0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
1bef0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
1bf00 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
1bf10 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
1bf20 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1bf30 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
1bf40 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
1bf50 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
1bf60 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
1bf70 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
1bf80 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
1bf90 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
1bfa0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1bfb0 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
1bfc0 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
1bfd0 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
1bfe0 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
1bff0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1c000 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
1c010 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
1c020 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
1c030 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
1c040 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1c050 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
1c060 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
1c070 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1c080 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1c090 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
1c0a0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
1c0b0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1c0c0 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
1c0d0 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
1c0e0 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
1c0f0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1c100 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
1c110 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
1c120 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1c130 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72  timeout()].** or
1c140 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41   evaluating [PRA
1c150 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1c160 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20  =N] will change 
1c170 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
1c180 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65  ler and thus cle
1c190 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  ar any previousl
1c1a0 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c  y set busy handl
1c1b0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
1c1c0 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
1c1d0 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
1c1e0 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
1c1f0 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
1c200 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1c210 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1c220 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
1c230 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a  In other words,.
1c240 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1c250 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ler is not reent
1c260 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20  rant.  Any such 
1c270 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
1c280 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
1c290 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
1c2a0 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
1c2b0 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
1c2c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1c2d0 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
1c2e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1c2f0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1c300 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1c310 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1c320 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
1c330 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1c340 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
1c350 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ),void*);../*.**
1c360 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
1c370 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a   Busy Timeout.**
1c380 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1c390 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1c3a0 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
1c3b0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1c3c0 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
1c3d0 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
1c3e0 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
1c3f0 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
1c400 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
1c410 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
1c420 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
1c430 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
1c440 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
1c450 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1c460 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
1c470 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
1c480 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
1c490 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1c4a0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1c4b0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
1c4c0 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
1c4d0 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
1c4e0 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
1c4f0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
1c500 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  _BUSY]..**.** ^C
1c510 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
1c520 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
1c530 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
1c540 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
1c550 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
1c560 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
1c570 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1c580 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1c590 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1c5a0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
1c5b0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1c5c0 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79  nnection] at any
1c5d0 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
1c5e0 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
1c5f0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
1c600 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
1c610 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1c620 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
1c630 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
1c640 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
1c650 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1c660 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
1c670 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1c680 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74    [PRAGMA busy_t
1c690 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53 51 4c 49 54  imeout].*/.SQLIT
1c6a0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1c6b0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
1c6c0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
1c6d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c6e0 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
1c6f0 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
1c700 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d  ing Queries.** M
1c710 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1c720 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
1c730 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
1c740 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
1c750 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
1c760 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1c770 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
1c780 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
1c790 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
1c7a0 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
1c7b0 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
1c7c0 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
1c7d0 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
1c7e0 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
1c7f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1c800 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
1c810 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1c820 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
1c830 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
1c840 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
1c850 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
1c860 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
1c870 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
1c880 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
1c890 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
1c8a0 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
1c8b0 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
1c8c0 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
1c8d0 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
1c8e0 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
1c8f0 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
1c900 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
1c910 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1c920 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
1c930 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1c940 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
1c950 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1c960 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
1c970 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
1c980 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1c990 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
1c9a0 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
1c9b0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
1c9c0 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
1c9d0 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
1c9e0 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
1c9f0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1ca00 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
1ca10 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
1ca20 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
1ca30 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
1ca40 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
1ca50 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
1ca60 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
1ca70 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
1ca80 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
1ca90 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
1caa0 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
1cab0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1cac0 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
1cad0 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
1cae0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1caf0 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
1cb00 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
1cb10 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
1cb20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
1cb30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
1cb40 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
1cb50 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
1cb60 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
1cb70 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
1cb80 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
1cb90 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
1cba0 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
1cbb0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
1cbc0 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
1cbd0 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
1cbe0 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
1cbf0 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
1cc00 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
1cc10 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
1cc20 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1cc30 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1cc40 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
1cc50 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
1cc60 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
1cc70 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
1cc80 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
1cc90 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
1cca0 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
1ccb0 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
1ccc0 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
1ccd0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1cce0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
1ccf0 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
1cd00 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
1cd10 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
1cd20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
1cd30 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
1cd40 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
1cd50 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1cd60 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
1cd70 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
1cd80 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
1cd90 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
1cda0 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
1cdb0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1cdc0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1cdd0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
1cde0 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
1cdf0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1ce00 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
1ce10 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1ce20 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
1ce30 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1ce40 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
1ce50 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
1ce60 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
1ce70 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
1ce80 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
1ce90 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
1cea0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1ceb0 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
1cec0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1ced0 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
1cee0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1cef0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
1cf00 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1cf10 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
1cf20 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
1cf30 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
1cf40 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
1cf50 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
1cf60 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
1cf70 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
1cf80 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
1cf90 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
1cfa0 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
1cfb0 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
1cfc0 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
1cfd0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
1cfe0 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
1cff0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
1d000 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1d010 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
1d020 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1d030 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
1d040 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
1d050 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
1d060 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1d070 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
1d080 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
1d090 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
1d0a0 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
1d0b0 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
1d0c0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
1d0d0 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
1d0e0 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
1d0f0 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
1d100 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
1d110 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
1d120 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
1d130 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
1d140 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
1d150 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1d160 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
1d170 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1d180 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
1d190 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
1d1a0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1d1b0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
1d1c0 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
1d1d0 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
1d1e0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
1d1f0 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
1d200 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1d210 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
1d220 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
1d230 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
1d240 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
1d250 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
1d260 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
1d270 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
1d280 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
1d290 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
1d2a0 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
1d2b0 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
1d2c0 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
1d2d0 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
1d2e0 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
1d2f0 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
1d300 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
1d310 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
1d320 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1d330 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
1d340 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1d350 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1d360 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  PI int sqlite3_g
1d370 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
1d380 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1d390 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
1d3a0 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
1d3b0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1d3c0 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
1d3d0 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
1d3e0 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
1d3f0 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
1d400 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
1d410 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
1d420 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1d430 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
1d440 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1d450 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
1d460 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1d470 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
1d480 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
1d490 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
1d4a0 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
1d4b0 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
1d4c0 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  here */.);.SQLIT
1d4d0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1d4e0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
1d4f0 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
1d500 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
1d510 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
1d520 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
1d530 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1d540 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
1d550 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
1d560 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
1d570 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
1d580 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
1d590 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
1d5a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1d5b0 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20  understand most 
1d5c0 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26  of the common K&
1d5d0 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  R formatting opt
1d5e0 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f  ions,.** plus so
1d5f0 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f  me additional no
1d600 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61  n-standard forma
1d610 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65 6c  ts, detailed bel
1d620 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ow..** Note that
1d630 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72   some of the mor
1d640 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 74  e obscure format
1d650 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f  ting options fro
1d660 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69  m recent.** C-li
1d670 62 72 61 72 79 20 73 74 61 6e 64 61 72 64 73 20  brary standards 
1d680 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d  are omitted from
1d690 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61   this implementa
1d6a0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
1d6b0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1d6c0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
1d6d0 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
1d6e0 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
1d6f0 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
1d700 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
1d710 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
1d720 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
1d730 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
1d740 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
1d750 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
1d760 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
1d770 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1d780 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
1d790 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
1d7a0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
1d7b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1d7c0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
1d7d0 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
1d7e0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1d7f0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
1d800 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ing..**.** ^(The
1d810 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1d820 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
1d830 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
1d840 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
1d850 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1d860 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
1d870 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
1d880 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
1d890 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
1d8a0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1d8b0 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
1d8c0 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
1d8d0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
1d8e0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
1d8f0 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
1d900 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
1d910 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
1d920 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
1d930 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
1d940 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
1d950 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
1d960 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
1d970 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
1d980 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1d990 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
1d9a0 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
1d9b0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1d9c0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1d9d0 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
1d9e0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
1d9f0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
1da00 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
1da10 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1da20 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
1da30 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
1da40 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1da50 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
1da60 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
1da70 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
1da80 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
1da90 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
1daa0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1dab0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1dac0 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
1dad0 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
1dae0 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
1daf0 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
1db00 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
1db10 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
1db20 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
1db30 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
1db40 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
1db50 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
1db60 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
1db70 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
1db80 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
1db90 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
1dba0 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
1dbb0 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
1dbc0 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
1dbd0 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
1dbe0 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
1dbf0 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
1dc00 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
1dc10 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
1dc20 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
1dc30 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  The sqlite3_vsnp
1dc40 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1dc50 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72  is a varargs ver
1dc60 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  sion of sqlite3_
1dc70 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a  snprintf()..**.*
1dc80 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1dc90 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
1dca0 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
1dcb0 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
1dcc0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
1dcd0 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
1dce0 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
1dcf0 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
1dd00 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
1dd10 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
1dd20 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
1dd30 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
1dd40 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
1dd50 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64 20   "%Q", "%w" and 
1dd60 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
1dd70 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74  .** ^(The %q opt
1dd80 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1dd90 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62  s in that it sub
1dda0 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74  stitutes a nul-t
1ddb0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1ddc0 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
1ddd0 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
1dde0 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
1ddf0 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
1de00 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
1de10 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
1de20 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
1de30 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20   literal.)^  By 
1de40 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
1de50 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
1de60 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
1de70 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
1de80 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
1de90 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
1dea0 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
1deb0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
1dec0 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
1ded0 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
1dee0 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
1def0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1df00 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1df10 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
1df20 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
1df30 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
1df40 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1df50 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
1df60 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
1df70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1df80 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1df90 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1dfa0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1dfb0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1dfc0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1dfd0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
1dfe0 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
1dff0 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1e000 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1e010 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1e020 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1e030 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1e040 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
1e050 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
1e060 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
1e070 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
1e080 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
1e090 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
1e0a0 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
1e0b0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1e0c0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1e0d0 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1e0e0 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1e0f0 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
1e100 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
1e110 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1e120 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
1e130 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
1e140 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
1e150 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
1e160 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
1e170 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
1e180 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
1e190 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1e1a0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1e1b0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1e1c0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1e1d0 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
1e1e0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1e1f0 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
1e200 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
1e210 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
1e220 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
1e230 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
1e240 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
1e250 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
1e260 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
1e270 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
1e280 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ral..**.** ^(The
1e290 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
1e2a0 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
1e2b0 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
1e2c0 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
1e2d0 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
1e2e0 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
1e2f0 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
1e300 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
1e310 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
1e320 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
1e330 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
1e340 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
1e350 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
1e360 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
1e370 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53  le quotes).)^  S
1e380 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
1e390 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
1e3a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1e3b0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1e3c0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1e3d0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1e3e0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1e3f0 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
1e400 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1e410 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1e420 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1e430 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1e440 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1e450 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
1e460 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
1e470 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
1e480 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1e490 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
1e4a0 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
1e4b0 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
1e4c0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1e4d0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  r..**.** ^(The "
1e4e0 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %w" formatting o
1e4f0 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25  ption is like "%
1e500 71 22 20 65 78 63 65 70 74 20 74 68 61 74 20 69  q" except that i
1e510 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20  t expects to.** 
1e520 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74  be contained wit
1e530 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65  hin double-quote
1e540 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69 6e  s instead of sin
1e550 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 20  gle quotes, and 
1e560 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 68  it.** escapes th
1e570 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63  e double-quote c
1e580 68 61 72 61 63 74 65 72 20 69 6e 73 74 65 61 64  haracter instead
1e590 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d 71   of the single-q
1e5a0 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 65  uote.** characte
1e5b0 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20 66  r.)^  The "%w" f
1e5c0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1e5d0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
1e5e0 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69 6e   safely insertin
1e5f0 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 63  g.** table and c
1e600 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f  olumn names into
1e610 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20 53   a constructed S
1e620 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
1e630 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
1e640 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1e650 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
1e660 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
1e670 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
1e680 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
1e690 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
1e6a0 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
1e6b0 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
1e6c0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
1e6d0 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
1e6e0 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
1e6f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  /.SQLITE_API cha
1e700 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
1e710 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
1e720 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..);.SQLITE_API 
1e730 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
1e740 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1e750 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51  r*, va_list);.SQ
1e760 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
1e770 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1e780 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1e790 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c  char*, ...);.SQL
1e7a0 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
1e7b0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1e7c0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1e7d0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1e7e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e7f0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1e800 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1e810 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1e820 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1e830 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1e840 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1e850 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1e860 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1e870 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1e880 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1e890 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1e8a0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1e8b0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1e8c0 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1e8d0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1e8e0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1e8f0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1e900 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1e910 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1e920 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1e930 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1e940 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1e950 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1e960 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1e970 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1e980 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1e990 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1e9a0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1e9b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1e9c0 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1e9d0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1e9e0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1e9f0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1ea00 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1ea10 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1ea20 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1ea30 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1ea40 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1ea50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1ea60 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1ea70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
1ea80 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1ea90 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77  c64(N) routine w
1eaa0 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a  orks just like.*
1eab0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1eac0 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  (N) except that 
1ead0 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  N is an unsigned
1eae0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1eaf0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1eb00 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e  signed 32-bit in
1eb10 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  teger..**.** ^Ca
1eb20 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
1eb30 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
1eb40 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
1eb50 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1eb60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1eb70 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1eb80 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
1eb90 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
1eba0 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
1ebb0 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71  reused.  ^The sq
1ebc0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
1ebd0 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
1ebe0 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
1ebf0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1ec00 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
1ec10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1ec20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
1ec30 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
1ec40 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
1ec50 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
1ec60 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
1ec70 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
1ec80 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
1ec90 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
1eca0 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
1ecb0 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
1ecc0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
1ecd0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1ece0 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
1ecf0 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
1ed00 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1ed10 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
1ed20 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
1ed30 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
1ed40 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
1ed50 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
1ed60 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
1ed70 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
1ed80 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1ed90 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1eda0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1edb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1edc0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1edd0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1ede0 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1edf0 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1ee00 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20  allocation X to 
1ee10 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
1ee20 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
1ee30 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  X parameter to s
1ee40 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1ee50 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ,N).** is a NULL
1ee60 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
1ee70 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
1ee80 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
1ee90 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
1eea0 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20  lloc(N)..** ^If 
1eeb0 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
1eec0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1eed0 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20  oc(X,N) is zero 
1eee0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
1eef0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1ef00 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
1ef10 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
1ef20 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
1ef30 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  X)..** ^sqlite3_
1ef40 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
1ef50 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1ef60 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
1ef70 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
1ef80 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1ef90 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
1efa0 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
1efb0 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ory is available
1efc0 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
1efd0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
1efe0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
1eff0 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
1f000 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
1f010 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
1f020 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
1f030 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1f040 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
1f050 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
1f060 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74  alloc(X,N) and t
1f070 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1f080 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
1f090 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
1f0a0 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1f0b0 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
1f0c0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74  positive, then t
1f0d0 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f  he.** prior allo
1f0e0 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72  cation is not fr
1f0f0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1f100 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1f110 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  4(X,N) interface
1f120 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  s works the same
1f130 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   as.** sqlite3_r
1f140 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65  ealloc(X,N) exce
1f150 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36  pt that N is a 6
1f160 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  4-bit unsigned i
1f170 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1f180 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69  * of a 32-bit si
1f190 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  gned integer..**
1f1a0 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d  .** ^If X is a m
1f1b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1f1c0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
1f1d0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1f1e0 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  3_malloc(),.** s
1f1f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1f200 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1f210 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  oc(), or sqlite3
1f220 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68  _realloc64(), th
1f230 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73  en.** sqlite3_ms
1f240 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74  ize(X) returns t
1f250 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20  he size of that 
1f260 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1f270 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  n in bytes..** ^
1f280 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1f290 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73  ed by sqlite3_ms
1f2a0 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20  ize(X) might be 
1f2b0 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
1f2c0 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74  number.** of byt
1f2d0 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65  es requested whe
1f2e0 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65  n X was allocate
1f2f0 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e  d.  ^If X is a N
1f300 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1f310 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1f320 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72  e(X) returns zer
1f330 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20  o.  If X points 
1f340 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61  to something tha
1f350 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20  t is not.** the 
1f360 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d  beginning of mem
1f370 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
1f380 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20  or if it points 
1f390 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a  to a formerly.**
1f3a0 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c   valid memory al
1f3b0 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61  location that ha
1f3c0 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64  s now been freed
1f3d0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
1f3e0 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ior.** of sqlite
1f3f0 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e  3_msize(X) is un
1f400 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73  defined and poss
1f410 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ibly harmful..**
1f420 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1f430 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1f440 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71  te3_malloc(), sq
1f450 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1f460 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1f470 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69  oc64(), and sqli
1f480 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a  te3_realloc64().
1f490 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1f4a0 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1f4b0 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1f4c0 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1f4d0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1f4e0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1f4f0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1f500 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1f510 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1f520 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1f530 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1f540 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1f550 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1f560 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1f570 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1f580 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1f590 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1f5a0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1f5b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1f5c0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1f5d0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1f5e0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1f5f0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1f600 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1f610 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1f620 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1f630 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1f640 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1f650 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1f660 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1f670 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1f680 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1f690 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1f6a0 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1f6b0 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1f6c0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1f6d0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1f6e0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1f6f0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1f700 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1f710 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1f720 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1f730 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1f740 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1f750 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1f760 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
1f770 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
1f780 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
1f790 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
1f7a0 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
1f7b0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
1f7c0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1f7d0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
1f7e0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
1f7f0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
1f800 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
1f810 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1f820 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
1f830 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
1f840 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
1f850 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
1f860 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
1f870 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1f880 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1f890 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
1f8a0 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
1f8b0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
1f8c0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
1f8d0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
1f8e0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
1f8f0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
1f900 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
1f910 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
1f920 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
1f930 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1f940 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1f950 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  alloc()]..*/.SQL
1f960 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
1f970 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
1f980 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1f990 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
1f9a0 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e  oc64(sqlite3_uin
1f9b0 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t64);.SQLITE_API
1f9c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72   void *sqlite3_r
1f9d0 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
1f9e0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
1f9f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1fa00 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71  lloc64(void*, sq
1fa10 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53  lite3_uint64);.S
1fa20 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1fa30 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
1fa40 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  *);.SQLITE_API s
1fa50 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71  qlite3_uint64 sq
1fa60 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64  lite3_msize(void
1fa70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1fa80 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1fa90 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
1faa0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
1fab0 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
1fac0 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
1fad0 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
1fae0 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
1faf0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
1fb00 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
1fb10 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
1fb20 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1fb30 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
1fb40 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
1fb50 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1fb60 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
1fb70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
1fb80 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1fb90 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
1fba0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
1fbb0 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d  of bytes.** of m
1fbc0 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
1fbd0 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
1fbe0 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
1fbf0 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  eed)..** ^The [s
1fc00 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1fc10 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
1fc20 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
1fc30 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20  aximum.** value 
1fc40 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  of [sqlite3_memo
1fc50 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65  ry_used()] since
1fc60 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1fc70 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74  mark.** was last
1fc80 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61   reset.  ^The va
1fc90 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
1fca0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1fcb0 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1fcc0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1fcd0 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63  highwater()] inc
1fce0 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61  lude any overhea
1fcf0 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51  d.** added by SQ
1fd00 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
1fd10 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
1fd20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1fd30 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65  ,.** but not ove
1fd40 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
1fd50 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
1fd60 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
1fd70 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
1fd80 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
1fd90 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
1fda0 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1fdb0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1fdc0 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
1fdd0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
1fde0 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  f.** [sqlite3_me
1fdf0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
1fe00 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
1fe10 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
1fe20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1fe30 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20  highwater()] is 
1fe40 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75  true.  ^The valu
1fe50 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
1fe60 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1fe70 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
1fe80 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
1fe90 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74   mark.** prior t
1fea0 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
1feb0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
1fec0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1fed0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1fee0 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  d);.SQLITE_API s
1fef0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1ff00 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1ff10 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
1ff20 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
1ff30 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
1ff40 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
1ff50 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
1ff60 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
1ff70 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
1ff80 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
1ff90 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
1ffa0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
1ffb0 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
1ffc0 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
1ffd0 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
1ffe0 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
1fff0 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
20000 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
20010 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
20020 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
20030 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
20040 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
20050 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
20060 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
20070 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
20080 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
20090 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
200a0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
200b0 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
200c0 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
200d0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
200e0 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
200f0 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
20100 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
20110 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50  fer P..** ^The P
20120 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62   parameter can b
20130 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
20140 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73  ..**.** ^If this
20150 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74   routine has not
20160 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79   been previously
20170 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68   called or if th
20180 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61  e previous.** ca
20190 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68  ll had N less th
201a0 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c  an one or a NULL
201b0 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20   pointer for P, 
201c0 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73  then the PRNG is
201d0 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67  .** seeded using
201e0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
201f0 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52  ined from the xR
20200 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
20210 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75   of.** the defau
20220 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
20230 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20   object..** ^If 
20240 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
20250 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
20260 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20  e had an N of 1 
20270 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a  or more and a.**
20280 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e   non-NULL P then
20290 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
202a0 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
202b0 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
202c0 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
202d0 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
202e0 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
202f0 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
20300 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
20310 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61   void sqlite3_ra
20320 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
20330 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
20340 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
20350 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
20360 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
20370 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
20380 65 33 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e3.** KEYWORDS: 
20390 7b 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c  {authorizer call
203a0 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  back}.**.** ^Thi
203b0 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
203c0 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ers an authorize
203d0 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
203e0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
203f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
20400 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
20410 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
20420 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
20430 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20440 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
20450 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
20460 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
20470 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
20480 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
20490 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
204a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
204b0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
204c0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
204d0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
204e0 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74  re16_v2()].  ^At
204f0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
20500 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
20510 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
20520 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
20530 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
20540 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
20550 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
20560 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20570 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
20580 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
20590 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
205a0 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
205b0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
205c0 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
205d0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
205e0 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
205f0 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
20600 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
20610 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
20620 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
20630 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
20640 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
20650 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
20660 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
20670 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
20680 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
20690 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
206a0 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
206b0 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
206c0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
206d0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
206e0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
206f0 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
20700 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
20710 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
20720 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
20730 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
20740 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
20750 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
20760 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
20770 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
20780 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
20790 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
207a0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
207b0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
207c0 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
207d0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
207e0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
207f0 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
20800 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
20810 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
20820 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
20830 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
20840 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
20850 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
20860 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
20870 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
20880 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
20890 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
208a0 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
208b0 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
208c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
208d0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
208e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
208f0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
20900 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
20910 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
20920 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
20930 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
20940 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
20950 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
20960 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
20970 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
20980 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
20990 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
209a0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
209b0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
209c0 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
209d0 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
209e0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
209f0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
20a00 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
20a10 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
20a20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
20a30 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
20a40 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
20a50 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
20a60 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
20a70 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
20a80 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
20a90 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
20aa0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
20ab0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
20ac0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
20ad0 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
20ae0 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
20af0 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
20b00 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
20b10 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
20b20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
20b30 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
20b40 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
20b50 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
20b60 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
20b70 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
20b80 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
20b90 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
20ba0 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
20bb0 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
20bc0 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
20bd0 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
20be0 5e 57 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73  ^When a table is
20bf0 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 61   referenced by a
20c00 20 5b 53 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f   [SELECT] but no
20c10 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61   column values a
20c20 72 65 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 20  re.** extracted 
20c30 66 72 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 20  from that table 
20c40 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e 20  (for example in 
20c50 61 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20  a query like.** 
20c60 22 53 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29  "SELECT count(*)
20c70 20 46 52 4f 4d 20 74 61 62 22 29 20 74 68 65 6e   FROM tab") then
20c80 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 41   the [SQLITE_REA
20c90 44 5d 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  D] authorizer ca
20ca0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76  llback.** is inv
20cb0 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 68  oked once for th
20cc0 61 74 20 74 61 62 6c 65 20 77 69 74 68 20 61 20  at table with a 
20cd0 4e 55 4c 4c 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  NULL column name
20ce0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
20cf0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
20d00 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
20d10 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
20d20 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
20d30 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
20d40 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
20d50 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
20d60 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
20d70 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
20d80 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
20d90 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
20da0 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
20db0 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
20dc0 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
20dd0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
20de0 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
20df0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
20e00 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
20e10 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
20e20 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
20e30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
20e40 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
20e50 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
20e60 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
20e70 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
20e80 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
20e90 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
20ea0 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
20eb0 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
20ec0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
20ed0 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
20ee0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
20ef0 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
20f00 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
20f10 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
20f20 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
20f30 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
20f40 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
20f50 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
20f60 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
20f70 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
20f80 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
20f90 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
20fa0 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
20fb0 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
20fc0 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
20fd0 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
20fe0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
20ff0 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
21000 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
21010 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
21020 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
21030 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
21040 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
21050 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
21060 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
21070 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
21080 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
21090 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
210a0 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
210b0 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
210c0 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
210d0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
210e0 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
210f0 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
21100 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
21110 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
21120 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
21130 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
21140 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
21150 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
21160 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
21170 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
21180 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
21190 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
211a0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
211b0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
211c0 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
211d0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
211e0 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
211f0 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
21200 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
21210 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
21220 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
21230 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
21240 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
21250 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21260 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
21270 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
21280 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
21290 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
212a0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
212b0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
212c0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
212d0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
212e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
212f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21300 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
21310 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
21320 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
21330 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
21340 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
21350 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
21360 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
21370 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
21380 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
21390 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
213a0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
213b0 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
213c0 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
213d0 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
213e0 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
213f0 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
21400 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
21410 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
21420 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
21430 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
21440 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
21450 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
21460 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
21470 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
21480 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
21490 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
214a0 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
214b0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
214c0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
214d0 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
214e0 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
214f0 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
21500 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
21510 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
21520 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
21530 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
21540 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
21550 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
21560 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
21570 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
21580 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
21590 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
215a0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
215b0 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
215c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
215d0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
215e0 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
215f0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
21600 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
21610 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
21620 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
21630 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
21640 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
21650 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
21660 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
21670 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
21680 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
21690 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
216a0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
216b0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
216c0 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
216d0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
216e0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
216f0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
21700 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
21710 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
21720 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
21730 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
21740 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
21750 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
21760 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
21770 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
21780 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
21790 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
217a0 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
217b0 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
217c0 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
217d0 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73   a [conflict res
217e0 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a  olution mode].**
217f0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74   returned from t
21800 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
21810 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
21820 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
21830 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
21840 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
21850 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
21860 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
21870 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21880 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
21890 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
218a0 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
218b0 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
218c0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
218d0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
218e0 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
218f0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
21900 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
21910 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
21920 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
21930 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
21940 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
21950 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
21960 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
21970 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
21980 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
21990 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
219a0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
219b0 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
219c0 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
219d0 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
219e0 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
219f0 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
21a00 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
21a10 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
21a20 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
21a30 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
21a40 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
21a50 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
21a60 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
21a70 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
21a80 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
21a90 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
21aa0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
21ab0 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
21ac0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
21ad0 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
21ae0 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
21af0 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
21b00 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
21b10 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
21b20 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
21b30 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
21b40 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
21b50 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
21b60 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
21b70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
21b80 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
21b90 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
21ba0 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
21bb0 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
21bc0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
21bd0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21be0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
21bf0 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
21c00 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
21c10 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
21c20 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
21c30 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
21c40 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
21c50 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
21c60 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
21c70 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
21c80 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
21c90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21ca0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21cb0 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
21cc0 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
21cd0 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
21ce0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
21cf0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
21d00 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
21d10 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
21d20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21d30 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
21d40 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
21d50 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21d60 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21d70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21d80 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
21d90 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
21da0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
21db0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21dc0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21dd0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
21de0 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
21df0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
21e00 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21e10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21e20 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
21e30 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
21e40 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
21e50 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21e60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21e70 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
21e80 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
21e90 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
21ea0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21eb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21ec0 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
21ed0 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
21ee0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
21ef0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
21f00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21f10 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
21f20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
21f30 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
21f40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21f50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21f60 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
21f70 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
21f80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
21f90 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21fa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21fb0 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
21fc0 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
21fd0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
21fe0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
21ff0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22000 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
22010 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
22020 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22030 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22040 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22050 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
22060 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
22070 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
22080 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
22090 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
220a0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
220b0 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
220c0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
220d0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
220e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
220f0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
22100 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
22110 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
22120 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22130 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
22140 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
22150 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
22160 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22170 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22180 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
22190 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
221a0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
221b0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
221c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
221d0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
221e0 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
221f0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
22200 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22210 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22220 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
22230 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
22240 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22250 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22260 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22270 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
22280 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
22290 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
222a0 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
222b0 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
222c0 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
222d0 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
222e0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
222f0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
22300 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22310 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
22320 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
22330 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22340 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22350 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22360 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
22370 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
22380 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
22390 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
223a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
223b0 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
223c0 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
223d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
223e0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
223f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22400 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
22410 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
22420 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
22430 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22440 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22450 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
22460 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
22470 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
22480 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22490 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
224a0 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
224b0 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
224c0 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
224d0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
224e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
224f0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
22500 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
22510 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22520 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22530 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
22540 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
22550 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
22560 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
22570 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22580 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
22590 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
225a0 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
225b0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
225c0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
225d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
225e0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
225f0 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
22600 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
22610 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
22620 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
22630 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
22640 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
22650 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
22660 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
22670 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
22680 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
22690 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
226a0 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
226b0 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
226c0 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
226d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
226e0 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
226f0 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  sed */.#define S
22700 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20  QLITE_RECURSIVE 
22710 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20             33   
22720 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
22730 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22740 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     */../*.** CAP
22750 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
22760 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
22770 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
22780 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
22790 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
227a0 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 55  re deprecated. U
227b0 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
227c0 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65  trace_v2()] inte
227d0 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64  rface.** instead
227e0 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73   of the routines
227f0 20 64 65 73 63 72 69 62 65 64 20 68 65 72 65 2e   described here.
22800 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
22810 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
22820 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
22830 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
22840 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
22850 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
22860 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
22870 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
22880 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
22890 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
228a0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
228b0 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
228c0 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
228d0 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
228e0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
228f0 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
22900 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
22910 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
22920 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
22930 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
22940 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
22950 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
22960 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
22970 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
22980 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
22990 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
229a0 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
229b0 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
229c0 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
229d0 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
229e0 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
229f0 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
22a00 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
22a10 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
22a20 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
22a30 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
22a40 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
22a50 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  gger.)^.**.** Th
22a60 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
22a70 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
22a80 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
22a90 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
22aa0 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67  imit.** the leng
22ab0 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  th of [bound par
22ac0 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f  ameter] expansio
22ad0 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20  n in the output 
22ae0 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  of sqlite3_trace
22af0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ()..**.** ^The c
22b00 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
22b10 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
22b20 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
22b30 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
22b40 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
22b50 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
22b60 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
22b70 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
22b80 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
22b90 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
22ba0 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
22bb0 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
22bc0 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
22bd0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
22be0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
22bf0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
22c00 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
22c10 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
22c20 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
22c30 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
22c40 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
22c50 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
22c60 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
22c70 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
22c80 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
22c90 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
22ca0 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
22cb0 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
22cc0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
22cd0 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
22ce0 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
22cf0 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
22d00 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
22d10 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ck.  The.** sqli
22d20 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75  te3_profile() fu
22d30 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64  nction is consid
22d40 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
22d50 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a  l and is.** subj
22d60 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
22d70 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
22d80 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53   of SQLite..*/.S
22d90 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
22da0 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
22db0 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
22dc0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
22dd0 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
22de0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
22df0 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  oid*);.SQLITE_AP
22e00 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
22e10 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TED void *sqlite
22e20 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
22e30 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
22e40 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
22e50 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
22e60 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
22e70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22e80 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76 65  F: SQL Trace Eve
22e90 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  nt Codes.** KEYW
22ea0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41  ORDS: SQLITE_TRA
22eb0 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  CE.**.** These c
22ec0 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66  onstants identif
22ed0 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65  y classes of eve
22ee0 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  nts that can be 
22ef0 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69  monitored.** usi
22f00 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
22f10 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63  trace_v2()] trac
22f20 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20  ing logic.  The 
22f30 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
22f40 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  * to [sqlite3_tr
22f50 61 63 65 5f 76 32 28 29 5d 20 69 73 20 61 6e 20  ace_v2()] is an 
22f60 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f  OR-ed combinatio
22f70 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  n of one or more
22f80 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
22f90 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20  wing constants. 
22fa0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
22fb0 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63  ment to the trac
22fc0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  e callback.** is
22fd0 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
22fe0 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e  owing constants.
22ff0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69  .**.** New traci
23000 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79  ng constants may
23010 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
23020 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
23030 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c  .** ^A trace cal
23040 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61  lback has four a
23050 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62  rguments: xCallb
23060 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a  ack(T,C,P,X)..**
23070 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74   ^The T argument
23080 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69   is one of the i
23090 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f 64 65  nteger type code
230a0 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65  s above..** ^The
230b0 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   C argument is a
230c0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
230d0 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73  text pointer pas
230e0 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a  sed in as the.**
230f0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
23100 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
23110 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65  ce_v2()]..** The
23120 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e   P and X argumen
23130 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20  ts are pointers 
23140 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64  whose meanings d
23150 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a  epend on T..**.*
23160 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
23170 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20  TE_TRACE_STMT]] 
23180 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
23190 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _STMT</dt>.** <d
231a0 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41  d>^An SQLITE_TRA
231b0 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b  CE_STMT callback
231c0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
231d0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
231e0 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62  ement.** first b
231f0 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e  egins running an
23200 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74  d possibly at ot
23210 68 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67  her times during
23220 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f   the.** executio
23230 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65  n of the prepare
23240 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63  d statement, suc
23250 68 20 61 73 20 61 74 20 74 68 65 20 73 74 61 72  h as at the star
23260 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69  t of each.** tri
23270 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e  gger subprogram.
23280 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
23290 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
232a0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
232b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
232c0 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  he X argument is
232d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
232e0 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20  string which.** 
232f0 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65  is the unexpande
23300 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68  d SQL text of th
23310 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
23320 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63  ment or an SQL c
23330 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20  omment .** that 
23340 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 69 6e  indicates the in
23350 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72  vocation of a tr
23360 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c  igger.  ^The cal
23370 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74  lback can comput
23380 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65  e.** the same te
23390 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  xt that would ha
233a0 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ve been returned
233b0 20 62 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b   by the legacy [
233c0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d  sqlite3_trace()]
233d0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79  .** interface by
233e0 20 75 73 69 6e 67 20 74 68 65 20 58 20 61 72 67   using the X arg
233f0 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67  ument when X beg
23400 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e  ins with "--" an
23410 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73  d invoking.** [s
23420 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
23430 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73  sql(P)] otherwis
23440 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
23450 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d  E_TRACE_PROFILE]
23460 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
23470 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a  CE_PROFILE</dt>.
23480 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54  ** <dd>^An SQLIT
23490 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20  E_TRACE_PROFILE 
234a0 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65  callback provide
234b0 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20  s approximately 
234c0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f  the same.** info
234d0 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72  rmation as is pr
234e0 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 5b 73  ovided by the [s
234f0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
23500 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e  ] callback..** ^
23510 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
23520 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
23530 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
23540 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a  tement] and the.
23550 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f  ** X argument po
23560 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74  ints to a 64-bit
23570 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
23580 73 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 20  s the estimated 
23590 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  of.** the number
235a0 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74   of nanosecond t
235b0 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64  hat the prepared
235c0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
235d0 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20  to run..** ^The 
235e0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f  SQLITE_TRACE_PRO
235f0 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73  FILE callback is
23600 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
23610 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  e statement fini
23620 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  shes..**.** [[SQ
23630 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d  LITE_TRACE_ROW]]
23640 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
23650 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  E_ROW</dt>.** <d
23660 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41  d>^An SQLITE_TRA
23670 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20  CE_ROW callback 
23680 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  is invoked whene
23690 76 65 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a  ver a prepared.*
236a0 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65  * statement gene
236b0 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72  rates a single r
236c0 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a  ow of result.  .
236d0 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  ** ^The P argume
236e0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
236f0 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
23700 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
23710 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e  the.** X argumen
23720 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a  t is unused..**.
23730 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
23740 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51  E_CLOSE]] <dt>SQ
23750 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
23760 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e  </dt>.** <dd>^An
23770 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c   SQLITE_TRACE_CL
23780 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  OSE callback is 
23790 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64  invoked when a d
237a0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
237b0 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a  ction closes..**
237c0 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
237d0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
237e0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
237f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63  onnection] objec
23800 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61  t.** and the X a
23810 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65  rgument is unuse
23820 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  d..** </dl>.*/.#
23830 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
23840 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30  ACE_STMT       0
23850 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  x01.#define SQLI
23860 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
23870 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65      0x02.#define
23880 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f   SQLITE_TRACE_RO
23890 57 20 20 20 20 20 20 20 20 30 78 30 34 0a 23 64  W        0x04.#d
238a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
238b0 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78  CE_CLOSE      0x
238c0 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  08../*.** CAPI3R
238d0 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f  EF: SQL Trace Ho
238e0 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ok.** METHOD: sq
238f0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
23900 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
23910 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72  2(D,M,X,P) inter
23920 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
23930 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a   trace callback.
23940 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67  ** function X ag
23950 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20  ainst [database 
23960 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75  connection] D, u
23970 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61  sing property ma
23980 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74  sk M.** and cont
23990 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20  ext pointer P.  
239a0 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61  ^If the X callba
239b0 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72  ck is.** NULL or
239c0 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69   if the M mask i
239d0 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61  s zero, then tra
239e0 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64  cing is disabled
239f0 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75  .  The.** M argu
23a00 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
23a10 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64  he bitwise OR-ed
23a20 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
23a30 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  ** zero or more 
23a40 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63  [SQLITE_TRACE] c
23a50 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  onstants..**.** 
23a60 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69  ^Each call to ei
23a70 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ther sqlite3_tra
23a80 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  ce() or sqlite3_
23a90 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72  trace_v2() overr
23aa0 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c  ides .** (cancel
23ab0 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c  s) any prior cal
23ac0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72  ls to sqlite3_tr
23ad0 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ace() or sqlite3
23ae0 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a  _trace_v2()..**.
23af0 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61  ** ^The X callba
23b00 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
23b10 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68  enever any of th
23b20 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66  e events identif
23b30 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20  ied by .** mask 
23b40 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69  M occur.  ^The i
23b50 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20 76 61  nteger return va
23b60 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c  lue from the cal
23b70 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74  lback is current
23b80 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74  ly.** ignored, t
23b90 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20 63  hough this may c
23ba0 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
23bb0 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62  releases.  Callb
23bc0 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ack.** implement
23bd0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65  ations should re
23be0 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73  turn zero to ens
23bf0 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61  ure future compa
23c00 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
23c10 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ^A trace callbac
23c20 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
23c30 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73  h four arguments
23c40 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50  : callback(T,C,P
23c50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61  ,X)..** ^The T a
23c60 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
23c70 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52  f the [SQLITE_TR
23c80 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74  ACE].** constant
23c90 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  s to indicate wh
23ca0 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77  y the callback w
23cb0 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e  as invoked..** ^
23cc0 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69  The C argument i
23cd0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
23ce0 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e  context pointer.
23cf0 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20  .** The P and X 
23d00 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f  arguments are po
23d10 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61  inters whose mea
23d20 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20  nings depend on 
23d30 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  T..**.** The sql
23d40 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20  ite3_trace_v2() 
23d50 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
23d60 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65  ended to replace
23d70 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
23d80 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
23d90 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20  e3_trace()] and 
23da0 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
23db0 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69  ()], both of whi
23dc0 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63  ch.** are deprec
23dd0 61 74 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ated..*/.SQLITE_
23de0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
23df0 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c 69  trace_v2(.  sqli
23e00 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64  te3*,.  unsigned
23e10 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78   uMask,.  int(*x
23e20 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e  Callback)(unsign
23e30 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76  ed,void*,void*,v
23e40 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  oid*),.  void *p
23e50 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Ctx.);../*.** CA
23e60 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
23e70 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
23e80 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
23e90 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
23ea0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
23eb0 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
23ec0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
23ed0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
23ee0 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
23ef0 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
23f00 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
23f10 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
23f20 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
23f30 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
23f40 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
23f50 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
23f60 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
23f70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
23f80 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
23f90 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
23fa0 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
23fb0 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
23fc0 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
23fd0 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
23fe0 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
23ff0 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
24000 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
24010 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
24020 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
24030 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
24040 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
24050 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62  approximate numb
24060 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
24070 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
24080 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
24090 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
240a0 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
240b0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
240c0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
240d0 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20    ^If N is less 
240e0 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68  than one then th
240f0 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61  e progress.** ha
24100 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65  ndler is disable
24110 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  d..**.** ^Only a
24120 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
24130 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
24140 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
24150 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
24160 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
24170 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
24180 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
24190 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
241a0 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
241b0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
241c0 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
241d0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
241e0 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
241f0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
24200 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
24210 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
24220 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
24230 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
24240 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
24250 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
24260 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
24270 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
24280 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
24290 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
242a0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
242b0 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
242c0 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
242d0 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
242e0 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
242f0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
24300 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
24310 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
24320 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
24330 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
24340 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
24350 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
24360 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
24370 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
24380 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
24390 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
243a0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
243b0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
243c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
243d0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
243e0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
243f0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
24400 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  *.*/.SQLITE_API 
24410 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
24420 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
24430 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
24440 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
24450 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
24460 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
24470 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
24480 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52  ection.** CONSTR
24490 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a  UCTOR: sqlite3.*
244a0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
244b0 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c  ines open an SQL
244c0 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ite database fil
244d0 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62  e as specified b
244e0 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61  y the .** filena
244f0 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68  me argument. ^Th
24500 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
24510 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
24520 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a  ed as UTF-8 for.
24530 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
24540 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
24550 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55  en_v2() and as U
24560 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
24570 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65  ive byte.** orde
24580 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  r for sqlite3_op
24590 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74  en16(). ^(A [dat
245a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
245b0 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61  ] handle is usua
245c0 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lly.** returned 
245d0 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69  in *ppDb, even i
245e0 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
245f0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63  s.  The only exc
24600 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a  eption is that.*
24610 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75  * if SQLite is u
24620 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
24630 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
24640 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
24650 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c  bject,.** a NULL
24660 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e   will be written
24670 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74   into *ppDb inst
24680 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72  ead of a pointer
24690 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
246a0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e  ].** object.)^ ^
246b0 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  (If the database
246c0 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f   is opened (and/
246d0 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63  or created) succ
246e0 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a  essfully, then.*
246f0 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  * [SQLITE_OK] is
24700 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
24710 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
24720 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
24730 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71  d.)^ ^The.** [sq
24740 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
24750 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
24760 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  sg16()] routines
24770 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
24780 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67  obtain.** an Eng
24790 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65  lish language de
247a0 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
247b0 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67   error following
247c0 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e   a failure of an
247d0 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  y.** of the sqli
247e0 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69  te3_open() routi
247f0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nes..**.** ^The 
24800 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
24810 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66   will be UTF-8 f
24820 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72 65  or databases cre
24830 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71  ated using.** sq
24840 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
24850 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24860 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74  ).  ^The default
24870 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61   encoding for da
24880 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74  tabases.** creat
24890 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
248a0 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62  _open16() will b
248b0 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  e UTF-16 in the 
248c0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
248d0 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  r..**.** Whether
248e0 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
248f0 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
24900 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
24910 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
24920 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
24930 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24940 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
24950 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
24960 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
24970 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
24980 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
24990 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
249a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
249b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
249c0 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
249d0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
249e0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
249f0 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
24a00 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
24a10 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
24a20 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
24a30 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
24a40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
24a50 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
24a60 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
24a70 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
24a80 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
24a90 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
24aa0 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
24ab0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
24ac0 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
24ad0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
24ae0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
24af0 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
24b00 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
24b10 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53  REDCACHE],.** [S
24b20 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
24b30 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72  TECACHE], and/or
24b40 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
24b50 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  I] flags:)^.**.*
24b60 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
24b70 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
24b80 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
24b90 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
24ba0 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
24bb0 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
24bc0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
24bd0 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
24be0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
24bf0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
24c00 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
24c10 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
24c20 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
24c30 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
24c40 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
24c50 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
24c60 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
24c70 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
24c80 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
24c90 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
24ca0 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
24cb0 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
24cc0 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
24cd0 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
24ce0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
24cf0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
24d00 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
24d10 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
24d20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
24d30 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
24d40 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
24d50 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
24d60 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
24d70 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
24d80 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
24d90 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
24da0 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
24db0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
24dc0 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
24dd0 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
24de0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
24df0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
24e00 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
24e10 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
24e20 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
24e30 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
24e40 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
24e50 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
24e60 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
24e70 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
24e80 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  e optionally com
24e90 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72  bined with other
24ea0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
24eb0 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49  _READONLY | SQLI
24ec0 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a  TE_OPEN_* bits].
24ed0 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
24ee0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
24ef0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
24f00 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
24f10 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
24f20 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
24f30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24f40 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
24f50 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
24f60 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
24f70 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
24f80 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
24f90 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
24fa0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
24fb0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
24fc0 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
24fd0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
24fe0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
24ff0 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
25000 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25010 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
25020 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
25030 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
25040 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
25050 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
25060 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
25070 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
25080 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
25090 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
250a0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
250b0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
250c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
250d0 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
250e0 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
250f0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
25100 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
25110 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
25120 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
25130 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
25140 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
25150 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
25160 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
25170 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
25180 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
25190 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
251a0 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
251b0 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
251c0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
251d0 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
251e0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
251f0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
25200 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
25210 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
25220 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
25230 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
25240 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
25250 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
25260 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
25270 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
25280 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
25290 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
252a0 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
252b0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
252c0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
252d0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
252e0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
252f0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
25300 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
25310 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
25320 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
25330 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
25340 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
25350 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
25360 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
25370 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d  tion.  ^This in-
25380 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
25390 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
253a0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
253b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
253c0 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
253d0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
253e0 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
253f0 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
25400 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
25410 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
25420 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
25430 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
25440 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
25450 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
25460 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
25470 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
25480 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
25490 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
254a0 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
254b0 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
254c0 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
254d0 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
254e0 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  biguity..**.** ^
254f0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
25500 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
25510 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
25520 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
25530 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
25540 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
25550 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74  d.  ^This privat
25560 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
25570 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
25580 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
25590 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
255a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
255b0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
255c0 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  [[URI filenames 
255d0 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  in sqlite3_open(
255e0 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65  )]] <h3>URI File
255f0 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  names</h3>.**.**
25600 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61   ^If [URI filena
25610 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69  me] interpretati
25620 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61  on is enabled, a
25630 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  nd the filename 
25640 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69  argument.** begi
25650 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  ns with "file:",
25660 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61   then the filena
25670 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  me is interprete
25680 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49  d as a URI. ^URI
25690 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  .** filename int
256a0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
256b0 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53  nabled if the [S
256c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
256d0 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69  flag is.** set i
256e0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
256f0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
25700 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
25710 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
25720 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
25730 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
25740 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
25750 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
25760 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
25770 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
25780 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
25790 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
257a0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
257b0 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
257c0 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20  sion 3.7.7, URI 
257d0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
257e0 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65  etation is turne
257f0 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61  d off.** by defa
25800 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20  ult, but future 
25810 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
25820 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20  te might enable 
25830 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  URI filename.** 
25840 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62  interpretation b
25850 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20  y default.  See 
25860 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d  "[URI filenames]
25870 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  " for additional
25880 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
25890 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  .**.** URI filen
258a0 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20  ames are parsed 
258b0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43  according to RFC
258c0 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55   3986. ^If the U
258d0 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a  RI contains an.*
258e0 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65  * authority, the
258f0 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74  n it must be eit
25900 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72  her an empty str
25910 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e  ing or the strin
25920 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74  g .** "localhost
25930 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  ". ^If the autho
25940 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65  rity is not an e
25950 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22  mpty string or "
25960 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a  localhost", an .
25970 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  ** error is retu
25980 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c  rned to the call
25990 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e  er. ^The fragmen
259a0 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
259b0 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65   URI, if .** pre
259c0 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64  sent, is ignored
259d0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
259e0 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f  uses the path co
259f0 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55  mponent of the U
25a00 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f  RI as the name o
25a10 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a  f the disk file.
25a20 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e  ** which contain
25a30 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
25a40 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67  ^If the path beg
25a50 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63  ins with a '/' c
25a60 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68  haracter, .** th
25a70 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  en it is interpr
25a80 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c  eted as an absol
25a90 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68  ute path. ^If th
25aa0 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20  e path does not 
25ab0 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61  begin .** with a
25ac0 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68   '/' (meaning th
25ad0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  at the authority
25ae0 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74   section is omit
25af0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49  ted from the URI
25b00 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61  ).** then the pa
25b10 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  th is interprete
25b20 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20  d as a relative 
25b30 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77  path. .** ^(On w
25b40 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73  indows, the firs
25b50 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
25b60 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20  n absolute path 
25b70 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73  .** is a drive s
25b80 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e  pecification (e.
25b90 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a  g. "C:").)^.**.*
25ba0 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65  * [[core URI que
25bb0 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a  ry parameters]].
25bc0 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d  ** The query com
25bd0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
25be0 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61  may contain para
25bf0 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
25c00 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65  interpreted.** e
25c10 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20  ither by SQLite 
25c20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20  itself, or by a 
25c30 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46  [VFS | custom VF
25c40 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
25c50 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64  ]..** SQLite and
25c60 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56   its built-in [V
25c70 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20  FSes] interpret 
25c80 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  the.** following
25c90 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
25ca0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
25cb0 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f     <li> <b>vfs</
25cc0 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70  b>: ^The "vfs" p
25cd0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
25ce0 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20  used to specify 
25cf0 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20  the name of.**  
25d00 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20     a VFS object 
25d10 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68  that provides th
25d20 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
25d30 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
25d40 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20  t should.**     
25d50 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73  be used to acces
25d60 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
25d70 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66  ile on disk. ^If
25d80 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
25d90 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e  set to.**     an
25da0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68   empty string th
25db0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62  e default VFS ob
25dc0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53  ject is used. ^S
25dd0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
25de0 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20  nown.**     VFS 
25df0 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66  is an error. ^If
25e00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
25e10 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
25e20 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73  he vfs option is
25e30 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c  .**     present,
25e40 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70   then the VFS sp
25e50 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
25e60 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63  ption takes prec
25e70 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20  edence over.**  
25e80 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73     the value pas
25e90 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
25ea0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
25eb0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25ec0 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
25ed0 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68  b>mode</b>: ^(Th
25ee0 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
25ef0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
25f00 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22  ither "ro", "rw"
25f10 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20  ,.**     "rwc", 
25f20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74  or "memory". Att
25f30 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69  empting to set i
25f40 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76  t to any other v
25f50 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61  alue is.**     a
25f60 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20  n error)^. .**  
25f70 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73     ^If "ro" is s
25f80 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74  pecified, then t
25f90 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
25fa0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f  pened for read-o
25fb0 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  nly .**     acce
25fc0 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74  ss, just as if t
25fd0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
25fe0 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68  READONLY] flag h
25ff0 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74  ad been set in t
26000 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64  he .**     third
26010 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
26020 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
26030 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
26040 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a  ion is set to .*
26050 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e  *     "rw", then
26060 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
26070 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
26080 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20  -write (but not 
26090 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20  create) .**     
260a0 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51  access, as if SQ
260b0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
260c0 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c  ITE (but not SQL
260d0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29  ITE_OPEN_CREATE)
260e0 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65   had .**     bee
260f0 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72  n set. ^Value "r
26100 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  wc" is equivalen
26110 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74  t to setting bot
26120 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  h .**     SQLITE
26130 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
26140 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  and SQLITE_OPEN_
26150 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65  CREATE.  ^If the
26160 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a   mode option is.
26170 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d  **     set to "m
26180 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75  emory" then a pu
26190 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  re [in-memory da
261a0 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76  tabase] that nev
261b0 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20  er reads.**     
261c0 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64  or writes from d
261d0 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74  isk is used. ^It
261e0 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20   is an error to 
261f0 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20  specify a value 
26200 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d  for.**     the m
26210 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  ode parameter th
26220 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72  at is less restr
26230 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74  ictive than that
26240 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
26250 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70       the flags p
26260 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69  assed in the thi
26270 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
26280 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26290 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
262a0 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54  <b>cache</b>: ^T
262b0 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
262c0 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
262d0 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22   either "shared"
262e0 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76   or.**     "priv
262f0 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69  ate". ^Setting i
26300 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73  t to "shared" is
26310 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
26320 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  etting the.**   
26330 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48    SQLITE_OPEN_SH
26340 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e  AREDCACHE bit in
26350 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
26360 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a  ent passed to.**
26370 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65       sqlite3_ope
26380 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67  n_v2(). ^Setting
26390 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d   the cache param
263a0 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65  eter to "private
263b0 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75  " is .**     equ
263c0 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
263d0 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  ng the SQLITE_OP
263e0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
263f0 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20  bit..**     ^If 
26400 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26410 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
26420 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65  e "cache" parame
26430 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69  ter is present i
26440 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66  n.**     a URI f
26450 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c  ilename, its val
26460 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79  ue overrides any
26470 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73   behavior reques
26480 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a  ted by setting.*
26490 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
264a0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f  N_PRIVATECACHE o
264b0 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48  r SQLITE_OPEN_SH
264c0 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a  AREDCACHE flag..
264d0 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70  **.**  <li> <b>p
264e0 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73  sow</b>: ^The ps
264f0 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64  ow parameter ind
26500 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20 6f  icates whether o
26510 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20  r not the.**    
26520 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72   [powersafe over
26530 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20  write] property 
26540 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74  does or does not
26550 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a   apply to the.**
26560 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64       storage med
26570 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20  ia on which the 
26580 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65  database file re
26590 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  sides..**.**  <l
265a0 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e  i> <b>nolock</b>
265b0 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61  : ^The nolock pa
265c0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
265d0 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d  lean query param
265e0 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63  eter.**     whic
265f0 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65  h if set disable
26600 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69  s file locking i
26610 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e  n rollback journ
26620 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a  al modes.  This.
26630 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 6c  **     is useful
26640 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61   for accessing a
26650 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66   database on a f
26660 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 64  ilesystem that d
26670 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73  oes not.**     s
26680 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20  upport locking. 
26690 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62   Caution:  Datab
266a0 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d  ase corruption m
266b0 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 74  ight result if t
266c0 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72  wo.**     or mor
266d0 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 74  e processes writ
266e0 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  e to the same da
266f0 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f  tabase and any o
26700 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20  ne of those.**  
26710 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65     processes use
26720 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a  s nolock=1..**.*
26730 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74  *  <li> <b>immut
26740 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69  able</b>: ^The i
26750 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74  mmutable paramet
26760 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
26770 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72  query.**     par
26780 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 69  ameter that indi
26790 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 64  cates that the d
267a0 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
267b0 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20  stored on.**    
267c0 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
267d0 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62  .  ^When immutab
267e0 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74  le is set, SQLit
267f0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
26800 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61  he.**     databa
26810 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62  se file cannot b
26820 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20  e changed, even 
26830 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 74  by a process wit
26840 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20  h higher.**     
26850 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73  privilege, and s
26860 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  o the database i
26870 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e  s opened read-on
26880 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69  ly and all locki
26890 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68  ng.**     and ch
268a0 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69  ange detection i
268b0 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75  s disabled.  Cau
268c0 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68  tion: Setting th
268d0 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20  e immutable.**  
268e0 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61     property on a
268f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
26900 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74  hat does in fact
26910 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75   change can resu
26920 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63  lt.**     in inc
26930 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65 73  orrect query res
26940 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  ults and/or [SQL
26950 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72  ITE_CORRUPT] err
26960 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20  ors..**     See 
26970 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
26980 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a  CAP_IMMUTABLE]..
26990 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75  **       .** </u
269a0 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66  l>.**.** ^Specif
269b0 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20  ying an unknown 
269c0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
269d0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
269e0 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74   of a URI is not
269f0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46   an.** error.  F
26a00 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
26a10 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75  f SQLite might u
26a20 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69  nderstand additi
26a30 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61  onal query.** pa
26a40 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22  rameters.  See "
26a50 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72  [query parameter
26a60 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d  s with special m
26a70 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65  eaning to SQLite
26a80 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  ]" for.** additi
26a90 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
26aa0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
26ab0 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d  lename examples]
26ac0 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61  ] <h3>URI filena
26ad0 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e  me examples</h3>
26ae0 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  .**.** <table bo
26af0 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63  rder="1" align=c
26b00 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e  enter cellpaddin
26b10 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  g=5>.** <tr><th>
26b20 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c   URI filenames <
26b30 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c  th> Results.** <
26b40 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
26b50 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
26b60 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
26b70 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
26b80 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
26b90 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e  rectory..** <tr>
26ba0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
26bb0 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e  fred/data.db<br>
26bc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
26bd0 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  e:///home/fred/d
26be0 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20  ata.db <br> .** 
26bf0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
26c00 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66  localhost/home/f
26c10 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
26c20 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
26c30 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61     Open the data
26c40 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65  base file "/home
26c50 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a  /fred/data.db"..
26c60 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
26c70 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65  ://darkstar/home
26c80 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74  /fred/data.db <t
26c90 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
26ca0 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73  An error. "darks
26cb0 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65  tar" is not a re
26cc0 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69  cognized authori
26cd0 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73  ty..** <tr><td s
26ce0 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63  tyle="white-spac
26cf0 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20  e:nowrap"> .**  
26d00 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
26d10 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61  C:/Documents%20a
26d20 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72  nd%20Settings/fr
26d30 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e  ed/Desktop/data.
26d40 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57  db.**     <td> W
26d50 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65  indows only: Ope
26d60 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
26d70 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64  .db" on fred's d
26d80 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a  esktop on drive.
26d90 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20  **          C:. 
26da0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32  Note that the %2
26db0 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68  0 escaping in th
26dc0 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f  is example is no
26dd0 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20  t strictly .**  
26de0 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72          necessar
26df0 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63  y - space charac
26e00 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  ters can be used
26e10 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20   literally.**   
26e20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69         in URI fi
26e30 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e  lenames..** <tr>
26e40 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
26e50 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d  b?mode=ro&cache=
26e60 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a  private <td> .**
26e70 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
26e80 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
26e90 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
26ea0 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d  ectory for read-
26eb0 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20  only access..** 
26ec0 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c           Regardl
26ed0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
26ee0 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63  r not shared-cac
26ef0 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c  he mode is enabl
26f00 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
26f10 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61    default, use a
26f20 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a   private cache..
26f30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
26f40 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
26f50 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74  .db?vfs=unix-dot
26f60 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20  file <td>.**    
26f70 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
26f80 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
26f90 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70  .db". Use the sp
26fa0 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d  ecial VFS "unix-
26fb0 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20  dotfile".**     
26fc0 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20 64       that uses d
26fd0 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63  ot-files in plac
26fe0 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73  e of posix advis
26ff0 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20  ory locking..** 
27000 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
27010 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f  ta.db?mode=reado
27020 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  nly <td> .**    
27030 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
27040 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f  "readonly" is no
27050 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e  t a valid option
27060 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20   for the "mode" 
27070 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f  parameter..** </
27080 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52  table>.**.** ^UR
27090 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  I hexadecimal es
270a0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28  cape sequences (
270b0 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74  %HH) are support
270c0 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61  ed within the pa
270d0 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20  th and.** query 
270e0 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20  components of a 
270f0 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d  URI. A hexadecim
27100 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
27110 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61  ce consists of a
27120 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e  .** percent sign
27130 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65   - "%" - followe
27140 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f  d by exactly two
27150 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67   hexadecimal dig
27160 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69  its .** specifyi
27170 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75  ng an octet valu
27180 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70  e. ^Before the p
27190 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d  ath or query com
271a0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20  ponents of a.** 
271b0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65  URI filename are
271c0 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68   interpreted, th
271d0 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75  ey are encoded u
271e0 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61  sing UTF-8 and a
271f0 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d  ll .** hexadecim
27200 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
27210 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20  ces replaced by 
27220 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f  a single byte co
27230 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
27240 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63  corresponding oc
27250 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f  tet. If this pro
27260 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61  cess generates a
27270 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20  n invalid UTF-8 
27280 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65  encoding,.** the
27290 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
272a0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  efined..**.** <b
272b0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
272c0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
272d0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
272e0 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
272f0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
27300 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
27310 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
27320 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
27330 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
27340 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
27350 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
27360 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
27370 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
27380 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
27390 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
273a0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
273b0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
273c0 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
273d0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
273e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
273f0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
27400 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  to Windows Runti
27410 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  me users:</b>  T
27420 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72  he temporary dir
27430 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73  ectory must be s
27440 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63  et.** prior to c
27450 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f  alling sqlite3_o
27460 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
27470 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68  _open_v2().  Oth
27480 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a  erwise, various.
27490 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74  ** features that
274a0 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65   require the use
274b0 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69   of temporary fi
274c0 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a  les may fail..**
274d0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
274e0 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
274f0 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45  ctory].*/.SQLITE
27500 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
27510 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
27520 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
27530 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
27540 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
27550 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
27560 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
27570 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
27580 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  dle */.);.SQLITE
27590 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
275a0 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
275b0 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
275c0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
275d0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
275e0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
275f0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
27600 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
27610 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c  handle */.);.SQL
27620 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
27630 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63  te3_open_v2(.  c
27640 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
27650 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
27660 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
27670 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
27680 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20   **ppDb,        
27690 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
276a0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69  db handle */.  i
276b0 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20  nt flags,       
276c0 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20         /* Flags 
276d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
276e0 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20  *zVfs        /* 
276f0 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75  Name of VFS modu
27700 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a  le to use */.);.
27710 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27720 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46   Obtain Values F
27730 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72  or URI Parameter
27740 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  s.**.** These ar
27750 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e  e utility routin
27760 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46  es, useful to VF
27770 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
27780 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a  s, that check.**
27790 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74   to see if a dat
277a0 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61  abase file was a
277b0 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69   URI that contai
277c0 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71  ned a specific q
277d0 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74  uery .** paramet
277e0 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62  er, and if so ob
277f0 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20  tains the value 
27800 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61  of that query pa
27810 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
27820 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62  f F is the datab
27830 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69  ase filename poi
27840 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f  nter passed into
27850 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74   the xOpen() met
27860 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53  hod of .** a VFS
27870 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
27880 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70  when the flags p
27890 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
278a0 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a  n() has one or .
278b0 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b  ** more of the [
278c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
278d0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e   or [SQLITE_OPEN
278e0 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73  _MAIN_DB] bits s
278f0 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74  et and.** P is t
27900 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71  he name of the q
27910 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20  uery parameter, 
27920 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
27930 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
27940 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  P) returns the v
27950 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a  alue of the P.**
27960 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74   parameter if it
27970 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c   exists or a NUL
27980 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64  L pointer if P d
27990 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61  oes not appear a
279a0 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61  s a .** query pa
279b0 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49  rameter on F.  I
279c0 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70  f P is a query p
279d0 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a  arameter of F.**
279e0 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74   has no explicit
279f0 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c   value, then sql
27a00 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
27a10 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a  er(F,P) returns.
27a20 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
27a30 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
27a40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
27a50 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
27a60 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73  ,P,B) routine as
27a70 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20  sumes that P is 
27a80 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72  a boolean.** par
27a90 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
27aa0 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66  ns true (1) or f
27ab0 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69  alse (0) accordi
27ac0 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a  ng to the value.
27ad0 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71  ** of P.  The sq
27ae0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
27af0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
27b00 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
27b10 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ) if the.** valu
27b20 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d  e of query param
27b30 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
27b40 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20   "yes", "true", 
27b50 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a  or "on" in any.*
27b60 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65  * case or if the
27b70 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
27b80 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75  th a non-zero nu
27b90 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73  mber.  The .** s
27ba0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
27bb0 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
27bc0 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  es returns false
27bd0 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75   (0) if the valu
27be0 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61  e of.** query pa
27bf0 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
27c00 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65   of "no", "false
27c10 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61  ", or "off" in a
27c20 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66  ny case or.** if
27c30 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
27c40 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63  s with a numeric
27c50 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20   zero.  If P is 
27c60 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70  not a query.** p
27c70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72  arameter on F or
27c80 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
27c90 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d   P is does not m
27ca0 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a  atch any of the.
27cb0 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73  ** above, then s
27cc0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
27cd0 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
27ce0 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20  s (B!=0)..**.** 
27cf0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
27d00 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75  int64(F,P,D) rou
27d10 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68  tine converts th
27d20 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74  e value of P int
27d30 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69  o a.** 64-bit si
27d40 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
27d50 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e   returns that in
27d60 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50  teger, or D if P
27d70 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69   does not.** exi
27d80 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75  st.  If the valu
27d90 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68  e of P is someth
27da0 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61  ing other than a
27db0 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a  n integer, then.
27dc0 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  ** zero is retur
27dd0 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46  ned..** .** If F
27de0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
27df0 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  er, then sqlite3
27e00 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
27e10 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ,P) returns NULL
27e20 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
27e30 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
27e40 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49  B) returns B.  I
27e50 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c  f F is not a NUL
27e60 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a  L pointer and.**
27e70 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
27e80 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  se file pathname
27e90 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51   pointer that SQ
27ea0 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f  Lite passed into
27eb0 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46   the xOpen.** VF
27ec0 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  S method, then t
27ed0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
27ee0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
27ef0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
27f00 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72  bably.** undesir
27f10 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  able..*/.SQLITE_
27f20 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
27f30 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
27f40 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72  meter(const char
27f50 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e   *zFilename, con
27f60 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29  st char *zParam)
27f70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
27f80 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
27f90 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20  lean(const char 
27fa0 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68  *zFile, const ch
27fb0 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20  ar *zParam, int 
27fc0 62 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54  bDefault);.SQLIT
27fd0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
27fe0 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  t64 sqlite3_uri_
27ff0 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72  int64(const char
28000 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
28010 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
28020 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28030 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
28040 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45  d Messages.** ME
28050 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
28060 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
28070 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f   recent sqlite3_
28080 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63  * API call assoc
28090 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b  iated with .** [
280a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
280b0 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74  ion] D failed, t
280c0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
280d0 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72  errcode(D) inter
280e0 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20  face.** returns 
280f0 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73  the numeric [res
28100 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78  ult code] or [ex
28110 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
28120 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20  de] for that.** 
28130 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20  API call..** If 
28140 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
28150 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75 63  API call was suc
28160 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e  cessful,.** then
28170 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
28180 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65  e from sqlite3_e
28190 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65  rrcode() is unde
281a0 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  fined..** ^The s
281b0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
281c0 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74  errcode().** int
281d0 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61  erface is the sa
281e0 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69  me except that i
281f0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
28200 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64   the .** [extend
28210 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
28220 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64  even when extend
28230 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
28240 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  are.** disabled.
28250 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28260 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
28270 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
28280 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
28290 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
282a0 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
282b0 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
282c0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
282d0 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
282e0 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  vely..** ^(Memor
282f0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
28300 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
28310 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
28320 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65  ternally..** The
28330 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
28340 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f  s not need to wo
28350 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e  rry about freein
28360 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
28370 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
28380 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
28390 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
283a0 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
283b0 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
283c0 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
283d0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
283e0 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a  functions.)^.**.
283f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28400 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61  errstr() interfa
28410 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45  ce returns the E
28420 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20  nglish-language 
28430 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73  text.** that des
28440 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75  cribes the [resu
28450 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46  lt code], as UTF
28460 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  -8..** ^(Memory 
28470 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
28480 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
28490 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
284a0 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75  rnally.** and mu
284b0 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20  st not be freed 
284c0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
284d0 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  on)^..**.** When
284e0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
284f0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
28500 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d   is in use, it m
28510 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63  ight be the.** c
28520 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e  ase that a secon
28530 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f  d error occurs o
28540 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  n a separate thr
28550 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a  ead in between.*
28560 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68  * the time of th
28570 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e  e first error an
28580 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68  d the call to th
28590 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ese interfaces..
285a0 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70  ** When that hap
285b0 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64  pens, the second
285c0 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
285d0 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68  eported since th
285e0 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ese.** interface
285f0 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20  s always report 
28600 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
28610 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69  result.  To avoi
28620 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20  d.** this, each 
28630 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69  thread can obtai
28640 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20  n exclusive use 
28650 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
28660 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
28670 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73  * by invoking [s
28680 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
28690 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  er]([sqlite3_db_
286a0 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72  mutex](D)) befor
286b0 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74  e beginning.** t
286c0 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f  o use D and invo
286d0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
286e0 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69  tex_leave]([sqli
286f0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
28700 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63  ) after.** all c
28710 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65  alls to the inte
28720 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65  rfaces listed he
28730 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64  re are completed
28740 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e  ..**.** If an in
28750 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
28760 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  th SQLITE_MISUSE
28770 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
28780 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61   interface.** wa
28790 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72  s invoked incorr
287a0 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70  ectly by the app
287b0 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68  lication.  In th
287c0 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20  at case, the.** 
287d0 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
287e0 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61  essage may or ma
287f0 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f  y not be set..*/
28800 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
28810 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
28820 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51  sqlite3 *db);.SQ
28830 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
28840 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
28850 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
28860 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  b);.SQLITE_API c
28870 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
28880 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
28890 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
288a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
288b0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
288c0 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  ite3*);.SQLITE_A
288d0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
288e0 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
288f0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
28900 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74  REF: Prepared St
28910 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
28920 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
28930 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
28940 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
28950 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
28960 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
28970 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
28980 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
28990 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a  statement that.*
289a0 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69  * has been compi
289b0 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20  led into binary 
289c0 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64  form and is read
289d0 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  y to be evaluate
289e0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f  d..**.** Think o
289f0 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  f each SQL state
28a00 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61  ment as a separa
28a10 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67  te computer prog
28a20 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69  ram.  The.** ori
28a30 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69  ginal SQL text i
28a40 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
28a50 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  A prepared state
28a60 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20  ment object .** 
28a70 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  is the compiled 
28a80 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c  object code.  Al
28a90 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f  l SQL must be co
28aa0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a  nverted into a.*
28ab0 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
28ac0 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63  ment before it c
28ad0 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  an be run..**.**
28ae0 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20   The life-cycle 
28af0 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74  of a prepared st
28b00 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
28b10 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65  sually goes like
28b20 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
28b30 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
28b40 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
28b50 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
28b60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
28b70 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  epare_v2()]..** 
28b80 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
28b90 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d   to [parameters]
28ba0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
28bb0 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
28bc0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
28bd0 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
28be0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
28bf0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
28c00 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
28c10 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
28c20 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
28c30 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
28c40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
28c50 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
28c60 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
28c70 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
28c80 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
28c90 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
28ca0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
28cb0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
28cc0 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  )]..** </ol>.*/.
28cd0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
28ce0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
28cf0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
28d00 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
28d10 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45  ime Limits.** ME
28d20 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
28d30 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
28d40 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
28d50 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
28d60 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
28d70 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
28d80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
28d90 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
28da0 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
28db0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
28dc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
28dd0 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
28de0 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
28df0 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
28e00 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
28e10 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
28e20 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
28e30 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
28e40 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
28e50 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
28e60 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
28e70 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
28e80 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
28e90 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
28ea0 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
28eb0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
28ec0 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
28ed0 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
28ee0 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
28ef0 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
28f00 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
28f10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
28f20 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
28f30 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
28f40 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
28f50 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
28f60 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
28f70 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
28f80 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
28f90 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
28fa0 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
28fb0 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
28fc0 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
28fd0 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
28fe0 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
28ff0 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
29000 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
29010 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
29020 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
29030 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
29040 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
29050 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
29060 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
29070 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
29080 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
29090 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
290a0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
290b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
290c0 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
290d0 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
290e0 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
290f0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
29100 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
29110 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
29120 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
29130 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
29140 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
29150 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
29160 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
29170 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
29180 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
29190 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
291a0 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
291b0 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
291c0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
291d0 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
291e0 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
291f0 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
29200 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
29210 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
29220 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
29230 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
29240 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
29250 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
29260 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
29270 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
29280 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
29290 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
292a0 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
292b0 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
292c0 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
292d0 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
292e0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
292f0 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
29300 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
29310 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
29320 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
29330 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
29340 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
29350 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
29360 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
29370 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
29380 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
29390 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
293a0 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
293b0 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
293c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
293d0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
293e0 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
293f0 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
29400 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
29410 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
29420 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
29430 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
29440 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
29450 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
29460 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
29470 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
29480 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
29490 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
294a0 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
294b0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
294c0 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54  leases..*/.SQLIT
294d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
294e0 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
294f0 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
29500 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
29510 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
29520 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
29530 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
29540 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
29550 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
29560 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
29570 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
29580 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
29590 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
295a0 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
295b0 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
295c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
295d0 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
295e0 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
295f0 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
29600 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
29610 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
29620 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
29630 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
29640 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
29650 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
29660 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
29670 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29680 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
29690 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
296a0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
296b0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
296c0 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
296d0 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
296e0 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
296f0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
29700 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
29710 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
29720 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
29730 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
29740 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
29750 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
29760 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
29770 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
29780 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29790 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
297a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
297b0 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
297c0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
297d0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
297e0 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
297f0 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
29800 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
29810 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
29820 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
29830 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
29840 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
29850 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
29860 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
29870 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
29880 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
29890 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
298a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
298b0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
298c0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
298d0 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
298e0 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
298f0 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
29900 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29910 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
29920 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
29930 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
29940 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
29950 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29960 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
29970 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
29980 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
29990 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
299a0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
299b0 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
299c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
299d0 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
299e0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
299f0 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
29a00 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
29a10 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
29a20 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
29a30 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
29a40 6d 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c 69 74  ment.  If [sqlit
29a50 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
29a60 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75 69 76   or.** the equiv
29a70 61 6c 65 6e 74 20 74 72 69 65 73 20 74 6f 20 61  alent tries to a
29a80 6c 6c 6f 63 61 74 65 20 73 70 61 63 65 20 66 6f  llocate space fo
29a90 72 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 69 73  r more than this
29aa0 20 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a   many opcodes.**
29ab0 20 69 6e 20 61 20 73 69 6e 67 6c 65 20 70 72 65   in a single pre
29ac0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c  pared statement,
29ad0 20 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d   an SQLITE_NOMEM
29ae0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
29af0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
29b00 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29b10 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e  FUNCTION_ARG]] ^
29b20 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
29b30 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
29b40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29b50 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
29b60 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
29b70 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
29b80 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
29b90 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d  LIMIT_ATTACHED]]
29ba0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29bb0 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
29bc0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29bd0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
29be0 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
29bf0 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
29c00 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
29c10 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
29c20 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a  ATTERN_LENGTH]].
29c30 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
29c40 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
29c50 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
29c60 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29c70 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
29c80 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
29c90 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
29ca0 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
29cb0 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
29cc0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29cd0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
29ce0 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ER]].** ^(<dt>SQ
29cf0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
29d00 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
29d10 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29d20 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20  um index number 
29d30 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65  of any [paramete
29d40 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  r] in an SQL sta
29d50 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  tement.)^.**.** 
29d60 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  [[SQLITE_LIMIT_T
29d70 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e  RIGGER_DEPTH]] ^
29d80 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
29d90 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
29da0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29db0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
29dc0 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
29dd0 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a  riggers.</dd>)^.
29de0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29df0 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
29e00 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ADS]] ^(<dt>SQLI
29e10 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
29e20 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20  THREADS</dt>.** 
29e30 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29e40 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69  number of auxili
29e50 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61  ary worker threa
29e60 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65  ds that a single
29e70 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
29e80 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61  atement] may sta
29e90 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rt.</dd>)^.** </
29ea0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
29eb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
29ec0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
29ed0 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
29ee0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
29ef0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
29f00 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
29f10 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
29f20 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
29f30 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
29f40 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
29f50 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
29f60 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
29f70 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29f80 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
29f90 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
29fa0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29fb0 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
29fc0 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
29fd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29fe0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
29ff0 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
2a000 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2a010 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
2a020 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
2a030 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2a040 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
2a050 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
2a060 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2a070 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
2a080 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
2a090 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a0a0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
2a0b0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
2a0c0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
2a0d0 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
2a0e0 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20  READS           
2a0f0 31 31 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  11.../*.** CAPI3
2a100 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
2a110 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
2a120 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
2a130 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
2a140 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  iler}.** METHOD:
2a150 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53   sqlite3.** CONS
2a160 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
2a170 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  _stmt.**.** To e
2a180 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
2a190 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
2a1a0 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
2a1b0 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
2a1c0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
2a1d0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
2a1e0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
2a1f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2a200 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
2a210 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a220 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
2a230 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
2a240 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
2a250 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2a260 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
2a270 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
2a280 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
2a290 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
2a2a0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
2a2b0 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
2a2c0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
2a2d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
2a2e0 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
2a2f0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
2a300 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
2a310 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
2a320 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
2a330 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
2a340 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
2a350 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
2a360 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
2a370 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
2a380 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
2a390 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2a3a0 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
2a3b0 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
2a3c0 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
2a3d0 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65  ment is negative
2a3e0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
2a3f0 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
2a400 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
2a410 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
2a420 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  e is positive, t
2a430 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a  hen it is the.**
2a440 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2a450 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
2a460 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a    ^If nByte is z
2a470 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65  ero, then no pre
2a480 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2a490 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e  nt is generated.
2a4a0 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65  .** If the calle
2a4b0 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65  r knows that the
2a4c0 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
2a4d0 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
2a4e0 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72  ed, then.** ther
2a4f0 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72  e is a small per
2a500 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
2a510 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e  ge to passing an
2a520 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
2a530 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20   that.** is the 
2a540 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2a550 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
2a560 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
2a570 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
2a580 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
2a590 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
2a5a0 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
2a5b0 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
2a5c0 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
2a5d0 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
2a5e0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
2a5f0 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
2a600 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
2a610 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
2a620 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
2a630 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
2a640 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
2a650 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
2a660 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
2a670 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
2a680 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
2a690 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
2a6a0 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
2a6b0 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
2a6c0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
2a6d0 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
2a6e0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
2a6f0 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
2a700 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
2a710 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
2a720 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
2a730 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
2a740 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
2a750 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
2a760 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
2a770 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
2a780 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
2a790 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
2a7a0 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
2a7b0 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
2a7c0 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
2a7d0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
2a7e0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
2a7f0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2a800 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
2a810 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
2a820 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
2a830 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
2a840 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
2a850 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
2a860 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
2a870 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
2a880 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
2a890 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
2a8a0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
2a8b0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
2a8c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2a8d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
2a8e0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2a8f0 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
2a900 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
2a910 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
2a920 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
2a930 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
2a940 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
2a950 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
2a960 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
2a970 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
2a980 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
2a990 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32  ..** ^In the "v2
2a9a0 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
2a9b0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2a9c0 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
2a9d0 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
2a9e0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
2a9f0 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
2aa00 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
2aa10 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
2aa20 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
2aa30 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
2aa40 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
2aa50 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
2aa60 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
2aa70 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
2aa80 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
2aa90 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
2aaa0 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
2aab0 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
2aac0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
2aad0 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
2aae0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
2aaf0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
2ab00 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
2ab10 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
2ab20 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
2ab30 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
2ab40 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79  t again. As many
2ab50 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f   as [SQLITE_MAX_
2ab60 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a  SCHEMA_RETRY].**
2ab70 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63   retries will oc
2ab80 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74  cur before sqlit
2ab90 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20  e3_step() gives 
2aba0 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  up and returns a
2abb0 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69  n error..** </li
2abc0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
2abd0 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
2abe0 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
2abf0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
2ac00 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
2ac10 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
2ac20 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
2ac30 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
2ac40 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
2ac50 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
2ac60 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
2ac70 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
2ac80 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
2ac90 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
2aca0 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
2acb0 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
2acc0 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
2acd0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
2ace0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2acf0 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
2ad00 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
2ad10 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
2ad20 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
2ad30 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
2ad40 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
2ad50 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
2ad60 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
2ad70 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
2ad80 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
2ad90 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
2ada0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
2adb0 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61   the specific va
2adc0 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61  lue bound to [pa
2add0 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
2ade0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
2adf0 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73   .** WHERE claus
2ae00 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  e might influenc
2ae10 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20  e the choice of 
2ae20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
2ae30 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74   statement,.** t
2ae40 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
2ae50 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  t will be automa
2ae60 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
2ae70 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20  ed, as if there 
2ae80 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73  had been .** a s
2ae90 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e  chema change, on
2aea0 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c   the first  [sql
2aeb0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
2aec0 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
2aed0 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65  change.** to the
2aee0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
2aef0 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
2af00 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74  of that [paramet
2af10 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70  er]. .** ^The sp
2af20 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20  ecific value of 
2af30 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61  WHERE-clause [pa
2af40 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69  rameter] might i
2af50 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a  nfluence the .**
2af60 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
2af70 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72   plan if the par
2af80 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65  ameter is the le
2af90 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
2afa0 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b  a [LIKE].** or [
2afb0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f  GLOB] operator o
2afc0 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
2afd0 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74  er is compared t
2afe0 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c  o an indexed col
2aff0 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b  umn.** and the [
2b000 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54  SQLITE_ENABLE_ST
2b010 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AT3] compile-tim
2b020 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
2b030 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  led..** </li>.**
2b040 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ol>.*/.SQLITE
2b050 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2b060 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
2b070 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2b080 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2b090 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2b0a0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
2b0b0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2b0c0 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
2b0d0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2b0e0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2b0f0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2b100 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2b110 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2b120 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2b130 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2b140 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2b150 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
2b160 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2b170 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2b180 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2b190 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
2b1a0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
2b1b0 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
2b1c0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2b1d0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2b1e0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2b1f0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2b200 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2b210 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2b220 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2b230 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2b240 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2b250 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2b260 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2b270 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2b280 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2b290 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2b2a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
2b2b0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2b2c0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2b2d0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2b2e0 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
2b2f0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2b300 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
2b310 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2b320 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2b330 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2b340 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
2b350 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2b360 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
2b370 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2b380 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2b390 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2b3a0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2b3b0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2b3c0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2b3d0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2b3e0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2b3f0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
2b400 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2b410 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2b420 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2b430 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
2b440 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2b450 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
2b460 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2b470 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2b480 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2b490 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2b4a0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2b4b0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2b4c0 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2b4d0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2b4e0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2b4f0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2b500 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2b510 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2b520 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2b530 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2b540 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2b550 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2b560 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2b570 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2b580 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
2b590 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2b5a0 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
2b5b0 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f  ent SQL.** METHO
2b5c0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2b5d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2b5e0 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66  e3_sql(P) interf
2b5f0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2b600 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79 20  inter to a copy 
2b610 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20  of the UTF-8.** 
2b620 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
2b630 20 63 72 65 61 74 65 20 5b 70 72 65 70 61 72 65   create [prepare
2b640 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 69  d statement] P i
2b650 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 74  f P was.** creat
2b660 65 64 20 62 79 20 65 69 74 68 65 72 20 5b 73 71  ed by either [sq
2b670 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2b680 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2b690 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2b6a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b6b0 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
2b6c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2b6d0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2b6e0 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  a UTF-8.** strin
2b6f0 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
2b700 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65   SQL text of pre
2b710 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2b720 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64  P with.** [bound
2b730 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70   parameters] exp
2b740 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  anded..**.** ^(F
2b750 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
2b760 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2b770 65 6e 74 20 69 73 20 63 72 65 61 74 65 64 20 75  ent is created u
2b780 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20  sing the SQL.** 
2b790 74 65 78 74 20 22 53 45 4c 45 43 54 20 24 61 62  text "SELECT $ab
2b7a0 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70  c,:xyz" and if p
2b7b0 61 72 61 6d 65 74 65 72 20 24 61 62 63 20 69 73  arameter $abc is
2b7c0 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65   bound to intege
2b7d0 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61  r 2345.** and pa
2b7e0 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20  rameter :xyz is 
2b7f0 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71  unbound, then sq
2b800 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c  lite3_sql() will
2b810 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f   return.** the o
2b820 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20  riginal string, 
2b830 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79  "SELECT $abc,:xy
2b840 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65  z" but sqlite3_e
2b850 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a  xpanded_sql().**
2b860 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45   will return "SE
2b870 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e  LECT 2345,NULL".
2b880 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
2b890 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2b8a0 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ql() interface r
2b8b0 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69  eturns NULL if i
2b8c0 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
2b8d0 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62  ry.** is availab
2b8e0 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  le to hold the r
2b8f0 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65  esult, or if the
2b900 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78   result would ex
2b910 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20  ceed the.** the 
2b920 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c  maximum string l
2b930 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64  ength determined
2b940 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
2b950 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  LIMIT_LENGTH]..*
2b960 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
2b970 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
2b980 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
2b990 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74   option limits t
2b9a0 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f  he size of.** bo
2b9b0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 65 78  und parameter ex
2b9c0 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20  pansions.  ^The 
2b9d0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41  [SQLITE_OMIT_TRA
2b9e0 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  CE] compile-time
2b9f0 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65  .** option cause
2ba00 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  s sqlite3_expand
2ba10 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61  ed_sql() to alwa
2ba20 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a  ys return NULL..
2ba30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  **.** ^The strin
2ba40 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2ba50 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 73 20  lite3_sql(P) is 
2ba60 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74  managed by SQLit
2ba70 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f  e and is.** auto
2ba80 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20  matically freed 
2ba90 77 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65  when the prepare
2baa0 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66  d statement is f
2bab0 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68  inalized..** ^Th
2bac0 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65  e string returne
2bad0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70  d by sqlite3_exp
2bae0 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e  anded_sql(P), on
2baf0 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c   the other hand,
2bb00 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20  .** is obtained 
2bb10 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2bb20 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74  lloc()] and must
2bb30 20 62 65 20 66 72 65 65 20 62 79 20 74 68 65 20   be free by the 
2bb40 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62  application.** b
2bb50 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  y passing it to 
2bb60 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
2bb70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2bb80 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2bb90 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
2bba0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 53 51  stmt *pStmt);.SQ
2bbb0 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
2bbc0 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2bbd0 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
2bbe0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2bbf0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
2bc00 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
2bc10 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
2bc20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20  The Database.** 
2bc30 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2bc40 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2bc50 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2bc60 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61  donly(X) interfa
2bc70 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
2bc80 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a  (non-zero) if.**
2bc90 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
2bca0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2bcb0 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f  ment] X makes no
2bcc0 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20   direct changes 
2bcd0 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  to.** the conten
2bce0 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
2bcf0 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  e file..**.** No
2bd00 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61  te that [applica
2bd10 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2bd20 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a   functions] or.*
2bd30 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
2bd40 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  s] might change 
2bd50 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64  the database ind
2bd60 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64  irectly as a sid
2bd70 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e  e effect.  .** ^
2bd80 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
2bd90 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2bda0 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69  defines a functi
2bdb0 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74  on "eval()" that
2bdc0 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69   .** calls [sqli
2bdd0 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65  te3_exec()], the
2bde0 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
2bdf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f  SQL statement wo
2be00 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  uld.** change th
2be10 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
2be20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66  through side-eff
2be30 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  ects:.**.** <blo
2be40 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
2be50 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28      SELECT eval(
2be60 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27  'DELETE FROM t1'
2be70 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f  ) FROM t2;.** </
2be80 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2be90 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61  >.**.** But beca
2bea0 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  use the [SELECT]
2beb0 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
2bec0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  not change the d
2bed0 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
2bee0 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65  directly, sqlite
2bef0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2bf00 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65  ) would still re
2bf10 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a  turn true.)^.**.
2bf20 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20  ** ^Transaction 
2bf30 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e  control statemen
2bf40 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49  ts such as [BEGI
2bf50 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52  N], [COMMIT], [R
2bf60 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41  OLLBACK],.** [SA
2bf70 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52  VEPOINT], and [R
2bf80 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71  ELEASE] cause sq
2bf90 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2bfa0 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
2bfb0 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74  true,.** since t
2bfc0 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  he statements th
2bfd0 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20  emselves do not 
2bfe0 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20  actually modify 
2bff0 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
2c000 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20  .** rather they 
2c010 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69  control the timi
2c020 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72  ng of when other
2c030 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69   statements modi
2c040 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62  fy the .** datab
2c050 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41  ase.  ^The [ATTA
2c060 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d  CH] and [DETACH]
2c070 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f   statements also
2c080 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65   cause.** sqlite
2c090 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2c0a0 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
2c0b0 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68   since, while th
2c0c0 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  ose statements.*
2c0d0 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e  * change the con
2c0e0 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20  figuration of a 
2c0f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2c100 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74  ion, they do not
2c110 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65   make .** change
2c120 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74  s to the content
2c130 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2c140 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a   files on disk..
2c150 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c160 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2c170 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2c180 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45 47 49  s true for [BEGI
2c190 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42 45 47  N] since.** [BEG
2c1a0 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74 73 20  IN] merely sets 
2c1b0 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73 2c 20  internal flags, 
2c1c0 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e 7c 42  but the [BEGIN|B
2c1d0 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45 5d 20  EGIN IMMEDIATE] 
2c1e0 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42 45  and.** [BEGIN|BE
2c1f0 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d 20 63  GIN EXCLUSIVE] c
2c200 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75 63 68  ommands do touch
2c210 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
2c220 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d so.** sqlite3_
2c230 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2c240 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 66 6f  returns false fo
2c250 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e 64 73  r those commands
2c260 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2c270 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
2c280 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
2c290 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2c2a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c2b0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
2c2c0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2c2d0 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
2c2e0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2c2f0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2c300 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2c310 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66  t_busy(S) interf
2c320 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
2c330 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74   (non-zero) if t
2c340 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2c350 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73  statement] S has
2c360 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74   been stepped at
2c370 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e   least once usin
2c380 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  g .** [sqlite3_s
2c390 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20  tep(S)] but has 
2c3a0 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63  neither run to c
2c3b0 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72  ompletion (retur
2c3c0 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  ned.** [SQLITE_D
2c3d0 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ONE] from [sqlit
2c3e0 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72  e3_step(S)]) nor
2c3f0 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75  .** been reset u
2c400 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
2c410 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73  set(S)].  ^The s
2c420 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2c430 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  (S).** interface
2c440 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69   returns false i
2c450 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f S is a NULL po
2c460 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20  inter.  If S is 
2c470 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70  not a .** NULL p
2c480 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f  ointer and is no
2c490 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  t a pointer to a
2c4a0 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64   valid [prepared
2c4b0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
2c4c0 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20  bject, then the 
2c4d0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
2c4e0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
2c4f0 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
2c500 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
2c510 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
2c520 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20   in combination 
2c530 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
2c540 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61  mt()].** to loca
2c550 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20  te all prepared 
2c560 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
2c570 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74  iated with a dat
2c580 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63  abase .** connec
2c590 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e  tion that are in
2c5a0 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72   need of being r
2c5b0 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20  eset.  This can 
2c5c0 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20  be used,.** for 
2c5d0 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67  example, in diag
2c5e0 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20  nostic routines 
2c5f0 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72  to search for pr
2c600 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65  epared .** state
2c610 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68  ments that are h
2c620 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63  olding a transac
2c630 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51  tion open..*/.SQ
2c640 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2c650 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
2c660 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2c670 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c680 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
2c690 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
2c6a0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
2c6b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c6c0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
2c6d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c6e0 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
2c6f0 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
2c700 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
2c710 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
2c720 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
2c730 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
2c740 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
2c750 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
2c760 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
2c770 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
2c780 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
2c790 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
2c7a0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2c7b0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
2c7c0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
2c7d0 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
2c7e0 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
2c7f0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
2c800 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2c810 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
2c820 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
2c830 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
2c840 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
2c850 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
2c860 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c870 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
2c880 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
2c890 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
2c8a0 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
2c8b0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2c8c0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
2c8d0 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
2c8e0 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
2c8f0 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
2c900 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
2c910 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
2c920 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
2c930 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c940 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  lue.  The.** [sq
2c950 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
2c960 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  )] interface can
2c970 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73   be used to cons
2c980 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20  truct a new .** 
2c990 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c9a0 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20  3_value from an 
2c9b0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2c9c0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
2c9d0 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
2c9e0 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
2c9f0 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
2ca00 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
2ca10 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
2ca20 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
2ca30 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
2ca40 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
2ca50 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2ca60 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
2ca70 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
2ca80 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
2ca90 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2caa0 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
2cab0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
2cac0 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
2cad0 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
2cae0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
2caf0 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
2cb00 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2cb10 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
2cb20 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
2cb30 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
2cb40 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
2cb50 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
2cb60 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2cb70 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
2cb80 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
2cb90 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
2cba0 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
2cbb0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
2cbc0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
2cbd0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2cbe0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2cbf0 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
2cc00 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
2cc10 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
2cc20 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
2cc30 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
2cc40 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
2cc50 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
2cc60 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
2cc70 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
2cc80 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
2cc90 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
2cca0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2ccb0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
2ccc0 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
2ccd0 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
2cce0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ccf0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2cd00 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
2cd10 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
2cd20 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
2cd30 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
2cd40 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2cd50 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2cd60 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
2cd70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2cd80 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
2cd90 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2cda0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2cdb0 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
2cdc0 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
2cdd0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2cde0 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
2cdf0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
2ce00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
2ce10 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
2ce20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2ce30 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
2ce40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2ce50 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
2ce60 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
2ce70 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
2ce80 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
2ce90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2cea0 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
2ceb0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2cec0 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71 6c 69  lite3_value sqli
2ced0 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
2cee0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
2cef0 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
2cf00 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
2cf10 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
2cf20 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
2cf30 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
2cf40 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
2cf50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
2cf60 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
2cf70 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
2cf80 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
2cf90 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
2cfa0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
2cfb0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2cfc0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2cfd0 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
2cfe0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2cff0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
2d000 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
2d010 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
2d020 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
2d030 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
2d040 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
2d050 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
2d060 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2d070 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2d080 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
2d090 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
2d0a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2d0b0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
2d0c0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
2d0d0 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
2d0e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
2d0f0 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
2d100 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2d110 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
2d120 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
2d130 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d140 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
2d150 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
2d160 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
2d170 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
2d180 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
2d190 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
2d1a0 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
2d1b0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
2d1c0 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
2d1d0 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
2d1e0 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
2d1f0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2d200 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  _stmt.**.** ^(In
2d210 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2d220 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
2d230 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d240 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
2d250 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
2d260 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
2d270 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
2d280 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
2d290 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
2d2a0 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
2d2b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2d2c0 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
2d2d0 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
2d2e0 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
2d2f0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
2d300 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2d310 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
2d320 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
2d330 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
2d340 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
2d350 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
2d360 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
2d370 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
2d380 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
2d390 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
2d3a0 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
2d3b0 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
2d3c0 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
2d3d0 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
2d3e0 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
2d3f0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2d400 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
2d410 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
2d420 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2d430 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
2d440 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2d450 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
2d460 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
2d470 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2d480 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
2d490 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
2d4a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2d4b0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
2d4c0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
2d4d0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2d4e0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2d4f0 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
2d500 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
2d510 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
2d520 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2d530 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
2d540 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
2d550 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
2d560 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
2d570 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
2d580 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2d590 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
2d5a0 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
2d5b0 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
2d5c0 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
2d5d0 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
2d5e0 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
2d5f0 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
2d600 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
2d610 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2d620 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2d630 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
2d640 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
2d650 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
2d660 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
2d670 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
2d680 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
2d690 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
2d6a0 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
2d6b0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
2d6c0 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
2d6d0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2d6e0 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
2d6f0 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
2d700 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
2d710 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
2d720 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
2d730 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
2d740 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
2d750 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2d760 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
2d770 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2d780 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  xt16().** or sql
2d790 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2d7a0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2d7b0 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  er then the four
2d7c0 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  th parameter.** 
2d7d0 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74  is ignored and t
2d7e0 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73  he end result is
2d7f0 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c   the same as sql
2d800 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29  ite3_bind_null()
2d810 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
2d820 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
2d830 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
2d840 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
2d850 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2d860 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2d870 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
2d880 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
2d890 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
2d8a0 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
2d8b0 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
2d8c0 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
2d8d0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
2d8e0 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
2d8f0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2d900 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2d910 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
2d920 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2d930 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  ).** is negative
2d940 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74  , then the lengt
2d950 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
2d960 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
2d970 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
2d980 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
2d990 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
2d9a0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2d9b0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2d9c0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2d9d0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a  negative, then.*
2d9e0 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  * the behavior i
2d9f0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2da00 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  If a non-negativ
2da10 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2da20 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  er is provided t
2da30 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2da40 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ext().** or sqli
2da50 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2da60 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2da70 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a  d_text64() then.
2da80 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  ** that paramete
2da90 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
2daa0 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
2dab0 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
2dac0 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
2dad0 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
2dae0 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
2daf0 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
2db00 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
2db10 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
2db20 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
2db30 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
2db40 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
2db50 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
2db60 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
2db70 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
2db80 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
2db90 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
2dba0 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
2dbb0 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
2dbc0 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
2dbd0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
2dbe0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2dbf0 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
2dc00 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42  ment to the BLOB
2dc10 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64   and string bind
2dc20 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ing interfaces.*
2dc30 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  * is a destructo
2dc40 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
2dc50 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
2dc60 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
2dc70 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
2dc80 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
2dc90 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2dca0 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
2dcb0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
2dcc0 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
2dcd0 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
2dce0 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e   bind API fails.
2dcf0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
2dd00 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
2dd10 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
2dd20 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
2dd30 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
2dd40 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
2dd50 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
2dd60 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
2dd70 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
2dd80 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
2dd90 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
2dda0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2ddb0 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
2ddc0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
2ddd0 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
2dde0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
2ddf0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
2de00 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
2de10 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
2de20 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
2de30 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2de40 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
2de50 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67  * ^The sixth arg
2de60 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2de70 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d  _bind_text64() m
2de80 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a  ust be one of.**
2de90 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
2dea0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
2deb0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2dec0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
2ded0 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63  16LE].** to spec
2dee0 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ify the encoding
2def0 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20   of the text in 
2df00 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2df10 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  ter.  If.** the 
2df20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2df30 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2df40 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f  ext64() is not o
2df50 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c  ne of the.** all
2df60 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77  owed values show
2df70 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74  n above, or if t
2df80 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
2df90 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a   is different.**
2dfa0 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69   from the encodi
2dfb0 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ng specified by 
2dfc0 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65  the sixth parame
2dfd0 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ter, then the be
2dfe0 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64  havior.** is und
2dff0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2e000 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2e010 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
2e020 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
2e030 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
2e040 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
2e050 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
2e060 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
2e070 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
2e080 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
2e090 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
2e0a0 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
2e0b0 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
2e0c0 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
2e0d0 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
2e0e0 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
2e0f0 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
2e100 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
2e110 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
2e120 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
2e130 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
2e140 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
2e150 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
2e160 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
2e170 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
2e180 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
2e190 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
2e1a0 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
2e1b0 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
2e1c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2e1d0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2e1e0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
2e1f0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
2e200 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2e210 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
2e220 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2e230 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
2e240 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2e250 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
2e260 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
2e270 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
2e280 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
2e290 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
2e2a0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
2e2b0 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
2e2c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
2e2d0 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
2e2e0 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
2e2f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2e300 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2e310 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
2e320 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
2e330 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
2e340 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
2e350 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
2e360 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
2e370 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
2e380 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
2e390 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
2e3a0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
2e3b0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
2e3c0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2e3d0 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
2e3e0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
2e3f0 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
2e400 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
2e410 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
2e420 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
2e430 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74  TE_TOOBIG] might
2e440 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20   be returned if 
2e450 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74  the size of a st
2e460 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20  ring or BLOB.** 
2e470 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69  exceeds limits i
2e480 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  mposed by [sqlit
2e490 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
2e4a0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29  E_LIMIT_LENGTH])
2e4b0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d   or.** [SQLITE_M
2e4c0 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e  AX_LENGTH]..** ^
2e4d0 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
2e4e0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
2e4f0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
2e500 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
2e510 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
2e520 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
2e530 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
2e540 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
2e550 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2e560 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2e570 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
2e580 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2e590 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
2e5a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2e5b0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2e5c0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2e5d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2e5e0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
2e5f0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2e600 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
2e610 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
2e620 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2e630 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36  lite3_bind_blob6
2e640 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2e650 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2e660 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
2e670 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
2e680 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
2e690 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
2e6a0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2e6b0 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
2e6c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e6d0 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49  t, double);.SQLI
2e6e0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2e6f0 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
2e700 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2e710 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2e720 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2e730 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
2e740 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
2e750 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49  te3_int64);.SQLI
2e760 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2e770 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
2e780 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
2e790 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2e7a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2e7b0 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
2e7c0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
2e7d0 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69  ,int,void(*)(voi
2e7e0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
2e7f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2e800 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
2e810 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2e820 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
2e830 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2e840 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2e850 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2e860 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2e870 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
2e880 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  r*, sqlite3_uint
2e890 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
2e8a0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
2e8b0 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73  d(*)(void*), uns
2e8c0 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64  igned char encod
2e8d0 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ing);.SQLITE_API
2e8e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2e8f0 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
2e900 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2e910 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
2e920 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2e930 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
2e940 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
2e950 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
2e960 6e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  n);.SQLITE_API i
2e970 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2e980 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74  zeroblob64(sqlit
2e990 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
2e9a0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
2e9b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e9c0 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
2e9d0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54  arameters.** MET
2e9e0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2e9f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
2ea00 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
2ea10 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
2ea20 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
2ea30 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
2ea40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ea50 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
2ea60 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
2ea70 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
2ea80 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
2ea90 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
2eaa0 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
2eab0 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
2eac0 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
2ead0 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
2eae0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
2eaf0 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
2eb00 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
2eb10 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
2eb20 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
2eb30 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
2eb40 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2eb50 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
2eb60 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
2eb70 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
2eb80 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
2eb90 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
2eba0 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
2ebb0 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
2ebc0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
2ebd0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
2ebe0 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20  e ?NNN form are 
2ebf0 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
2ec00 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
2ec10 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e list.)^.**.** 
2ec20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2ec30 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2ec40 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2ec50 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2ec60 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2ec70 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2ec80 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2ec90 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
2eca0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2ecb0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2ecc0 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
2ecd0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2ece0 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
2ecf0 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
2ed00 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ter.** METHOD: s
2ed10 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2ed20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2ed30 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2ed40 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(P,N) interfac
2ed50 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  e returns.** the
2ed60 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74   name of the N-t
2ed70 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  h [SQL parameter
2ed80 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] in the [prepar
2ed90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
2eda0 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65  .** ^(SQL parame
2edb0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
2edc0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
2edd0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
2ede0 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
2edf0 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
2ee00 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
2ee10 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
2ee20 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
2ee30 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
2ee40 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
2ee50 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
2ee60 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
2ee70 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
2ee80 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
2ee90 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20   the name.)^.** 
2eea0 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74  ^Parameters of t
2eeb0 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
2eec0 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
2eed0 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
2eee0 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
2eef0 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
2ef00 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e  nameless" or "an
2ef10 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
2ef20 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rs"..**.** ^The 
2ef30 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
2ef40 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
2ef50 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
2ef60 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c  *.** ^If the val
2ef70 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue N is out of r
2ef80 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e  ange or if the N
2ef90 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
2efa0 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
2efb0 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
2efc0 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ned.  ^The retur
2efd0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
2efe0 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
2eff0 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
2f000 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
2f010 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
2f020 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
2f030 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
2f040 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2f050 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
2f060 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2f070 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
2f080 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2f090 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2f0a0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2f0b0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2f0c0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
2f0d0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2f0e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2f0f0 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ex()]..*/.SQLITE
2f100 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
2f110 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  *sqlite3_bind_pa
2f120 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
2f130 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
2f140 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f150 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
2f160 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
2f170 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54  iven Name.** MET
2f180 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2f190 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
2f1a0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
2f1b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
2f1c0 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
2f1d0 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
2f1e0 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
2f1f0 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
2f200 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
2f210 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2f220 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2f230 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2f240 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
2f250 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
2f260 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
2f270 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
2f280 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
2f290 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
2f2a0 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
2f2b0 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
2f2c0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
2f2d0 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
2f2e0 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
2f2f0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
2f300 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
2f310 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2f320 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2f330 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2f340 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2f350 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2f360 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2f370 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2f380 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a  ter_name()]..*/.
2f390 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2f3a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2f3b0 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
2f3c0 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
2f3d0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
2f3e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2f3f0 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
2f400 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
2f410 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45   Statement.** ME
2f420 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2f430 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  mt.**.** ^Contra
2f440 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
2f450 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
2f460 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
2f470 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
2f480 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2f490 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
2f4a0 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
2f4b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2f4c0 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
2f4d0 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
2f4e0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
2f4f0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c   to NULL..*/.SQL
2f500 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2f510 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2f520 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
2f530 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f540 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
2f550 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
2f560 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
2f570 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2f580 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2f590 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2f5a0 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2f5b0 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
2f5c0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2f5d0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66   statement]. ^If
2f5e0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
2f5f0 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d 65  turns 0, that me
2f600 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65  ans the .** [pre
2f610 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f620 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74 61   returns no data
2f630 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
2f640 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e   [UPDATE])..** ^
2f650 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62 65  However, just be
2f660 63 61 75 73 65 20 74 68 69 73 20 72 6f 75 74 69  cause this routi
2f670 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73  ne returns a pos
2f680 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f 65  itive number doe
2f690 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68  s not.** mean th
2f6a0 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72  at one or more r
2f6b0 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c 6c  ows of data will
2f6c0 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   be returned.  ^
2f6d0 41 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  A SELECT stateme
2f6e0 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79  nt.** will alway
2f6f0 73 20 68 61 76 65 20 61 20 70 6f 73 69 74 69 76  s have a positiv
2f700 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2f710 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65 70  _count() but dep
2f720 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a  ending on the.**
2f730 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
2f740 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68  nstraints and th
2f750 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c  e table content,
2f760 20 69 74 20 6d 69 67 68 74 20 72 65 74 75 72 6e   it might return
2f770 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20   no rows..**.** 
2f780 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2f790 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
2f7a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2f7b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2f7c0 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
2f7d0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2f7e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2f7f0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
2f800 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d   Result Set.** M
2f810 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2f820 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
2f830 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2f840 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
2f850 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
2f860 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
2f870 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
2f880 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
2f890 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
2f8a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2f8b0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
2f8c0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2f8d0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2f8e0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
2f8f0 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
2f900 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2f910 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
2f920 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2f930 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
2f940 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
2f950 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2f960 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
2f970 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2f980 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
2f990 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
2f9a0 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
2f9b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2f9c0 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
2f9d0 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
2f9e0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
2f9f0 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
2fa00 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2fa10 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
2fa20 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
2fa30 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
2fa40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2fa50 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
2fa60 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2fa70 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2fa80 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2fa90 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2faa0 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2fab0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2fac0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2fad0 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2fae0 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2faf0 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
2fb00 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2fb10 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
2fb20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2fb30 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
2fb40 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
2fb50 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
2fb60 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
2fb70 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
2fb80 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
2fb90 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
2fba0 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
2fbb0 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
2fbc0 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
2fbd0 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
2fbe0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
2fbf0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  d..**.** ^The na
2fc00 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
2fc10 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
2fc20 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
2fc30 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
2fc40 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
2fc50 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
2fc60 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
2fc70 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
2fc80 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
2fc90 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
2fca0 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
2fcb0 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
2fcc0 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
2fcd0 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
2fce0 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  next..*/.SQLITE_
2fcf0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2fd00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2fd10 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2fd20 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54  *, int N);.SQLIT
2fd30 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2fd40 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2fd50 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2fd60 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
2fd70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2fd80 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
2fd90 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
2fda0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2fdb0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2fdc0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
2fdd0 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
2fde0 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
2fdf0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2fe00 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
2fe10 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
2fe20 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
2fe30 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
2fe40 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
2fe50 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
2fe60 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2fe70 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
2fe80 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
2fe90 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
2fea0 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
2feb0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
2fec0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
2fed0 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
2fee0 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
2fef0 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
2ff00 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
2ff10 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
2ff20 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
2ff30 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
2ff40 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2ff50 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
2ff60 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2ff70 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
2ff80 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
2ff90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
2ffa0 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
2ffb0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2ffc0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2ffd0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2ffe0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2fff0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
30000 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
30010 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
30020 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
30030 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
30040 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
30050 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
30060 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
30070 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
30080 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
30090 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
300a0 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
300b0 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
300c0 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
300d0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
300e0 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
300f0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
30100 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
30110 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
30120 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30130 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
30140 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
30150 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
30160 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
30170 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
30180 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
30190 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
301a0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
301b0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
301c0 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
301d0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
301e0 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
301f0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
30200 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
30210 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
30220 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
30230 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
30240 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
30250 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
30260 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
30270 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
30280 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
30290 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
302a0 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
302b0 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
302c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
302d0 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
302e0 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
302f0 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
30300 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
30310 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
30320 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
30330 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
30340 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
30350 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
30360 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
30370 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
30380 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
30390 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
303a0 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
303b0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
303c0 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
303d0 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
303e0 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
303f0 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
30400 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
30410 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
30420 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
30430 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
30440 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
30450 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
30460 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
30470 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
30480 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
30490 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
304a0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
304b0 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
304c0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
304d0 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
304e0 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
304f0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
30500 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
30510 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
30520 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
30530 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
30540 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
30550 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
30560 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
30570 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
30580 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
30590 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
305a0 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
305b0 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
305c0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
305d0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
305e0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
305f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
30600 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
30610 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
30620 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
30630 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
30640 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
30650 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
30660 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
30670 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
30680 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
30690 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
306a0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
306b0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
306c0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
306d0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
306e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
306f0 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
30700 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
30710 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
30720 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
30730 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
30740 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
30750 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
30760 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
30770 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
30780 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
30790 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
307a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
307b0 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
307c0 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
307d0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
307e0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
307f0 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
30800 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
30810 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
30820 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
30830 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
30840 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
30850 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
30860 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
30870 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
30880 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
30890 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
308a0 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
308b0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
308c0 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
308d0 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
308e0 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
308f0 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
30900 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
30910 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
30920 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
30930 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
30940 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
30950 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
30960 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
30970 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
30980 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
30990 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
309a0 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
309b0 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
309c0 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
309d0 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
309e0 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
309f0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
30a00 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
30a10 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
30a20 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
30a30 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
30a40 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
30a50 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
30a60 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
30a70 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
30a80 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
30a90 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
30aa0 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
30ab0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
30ac0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
30ad0 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
30ae0 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
30af0 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
30b00 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
30b10 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
30b20 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
30b30 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
30b40 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
30b50 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
30b60 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
30b70 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
30b80 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
30b90 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
30ba0 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
30bb0 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
30bc0 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
30bd0 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
30be0 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
30bf0 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
30c00 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
30c10 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
30c20 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
30c30 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
30c40 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
30c50 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
30c60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
30c70 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
30c80 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
30c90 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
30ca0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
30cb0 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
30cc0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
30cd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
30ce0 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
30cf0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f  atement.** METHO
30d00 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
30d10 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
30d20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30d30 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
30d40 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
30d50 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
30d60 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
30d70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
30d80 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
30d90 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
30da0 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
30db0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
30dc0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
30dd0 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
30de0 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
30df0 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
30e00 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
30e10 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
30e20 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
30e30 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
30e40 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
30e50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
30e60 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
30e70 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
30e80 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
30e90 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
30ea0 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
30eb0 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
30ec0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
30ed0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
30ee0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
30ef0 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
30f00 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
30f10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
30f20 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
30f30 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
30f40 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
30f50 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
30f60 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
30f70 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
30f80 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
30f90 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
30fa0 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
30fb0 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
30fc0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
30fd0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
30fe0 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
30ff0 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
31000 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
31010 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
31020 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
31030 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
31040 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
31050 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
31060 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
31070 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
31080 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
31090 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
310a0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
310b0 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
310c0 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
310d0 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
310e0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
310f0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
31100 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
31110 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
31120 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
31130 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
31140 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
31150 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
31160 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
31170 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
31180 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
31190 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
311a0 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
311b0 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
311c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
311d0 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
311e0 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
311f0 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
31200 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
31210 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
31220 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
31230 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
31240 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
31250 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
31260 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
31270 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
31280 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
31290 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
312a0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
312b0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
312c0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
312d0 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
312e0 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
312f0 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
31300 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
31310 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
31320 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
31330 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
31340 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
31350 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
31360 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
31370 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
31380 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
31390 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
313a0 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
313b0 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
313c0 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
313d0 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
313e0 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
313f0 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
31400 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
31410 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
31420 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
31430 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
31440 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
31450 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
31460 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
31470 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
31480 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
31490 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
314a0 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
314b0 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
314c0 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
314d0 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
314e0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
314f0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
31500 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
31510 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
31520 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
31530 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
31540 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
31550 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
31560 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
31570 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
31580 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
31590 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
315a0 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
315b0 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
315c0 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
315d0 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
315e0 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
315f0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
31600 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
31610 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
31620 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
31630 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
31640 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
31650 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
31660 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
31670 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
31680 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
31690 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
316a0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
316b0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
316c0 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
316d0 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
316e0 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
316f0 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
31700 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
31710 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
31720 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
31730 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
31740 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
31750 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
31760 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
31770 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
31780 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
31790 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
317a0 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
317b0 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
317c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
317d0 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
317e0 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
317f0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
31800 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
31810 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
31820 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
31830 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
31840 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
31850 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
31860 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
31870 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
31880 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
31890 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
318a0 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
318b0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
318c0 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
318d0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
318e0 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
318f0 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
31900 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
31910 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
31920 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
31930 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
31940 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
31950 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
31960 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
31970 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
31980 75 74 20 61 66 74 65 72 20 5b 76 65 72 73 69 6f  ut after [versio
31990 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61  n 3.6.23.1] ([da
319a0 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a  teof:3.6.23.1],.
319b0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
319c0 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
319d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
319e0 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
319f0 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
31a00 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
31a10 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
31a20 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
31a30 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
31a40 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
31a50 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
31a60 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
31a70 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
31a80 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
31a90 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
31aa0 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
31ab0 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
31ac0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
31ad0 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
31ae0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
31af0 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
31b00 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
31b10 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
31b20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
31b30 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
31b40 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
31b50 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
31b60 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
31b70 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
31b80 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
31b90 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
31ba0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
31bb0 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
31bc0 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
31bd0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
31be0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
31bf0 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
31c00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
31c10 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
31c20 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
31c30 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
31c40 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
31c50 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
31c60 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
31c70 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
31c80 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
31c90 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
31ca0 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
31cb0 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
31cc0 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
31cd0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
31ce0 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
31cf0 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
31d00 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
31d10 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
31d20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
31d30 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
31d40 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
31d50 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
31d60 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
31d70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
31d80 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
31d90 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
31da0 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
31db0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
31dc0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
31dd0 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
31de0 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
31df0 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
31e00 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
31e10 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
31e20 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c  ommended..*/.SQL
31e30 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
31e40 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
31e50 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
31e60 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
31e70 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
31e80 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d   result set.** M
31e90 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
31ea0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
31eb0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
31ec0 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
31ed0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
31ee0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
31ef0 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
31f00 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
31f10 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
31f20 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
31f30 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
31f40 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
31f50 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
31f60 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
31f70 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
31f80 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
31f90 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
31fa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
31fb0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
31fc0 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
31fd0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
31fe0 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
31ff0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
32000 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
32010 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
32020 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
32030 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
32040 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
32050 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
32060 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
32070 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
32080 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
32090 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
320a0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
320b0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
320c0 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
320d0 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
320e0 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
320f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
32100 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
32110 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
32120 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
32130 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
32140 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
32150 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
32160 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
32170 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
32180 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
32190 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
321a0 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
321b0 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
321c0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
321d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
321e0 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nt()].*/.SQLITE_
321f0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
32200 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
32210 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
32220 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32230 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
32240 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
32250 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
32260 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
32270 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
32280 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
32290 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
322a0 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
322b0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
322c0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
322d0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
322e0 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
322f0 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
32300 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
32310 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
32320 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
32330 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
32340 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
32350 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
32360 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
32370 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
32380 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
32390 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
323a0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
323b0 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
323c0 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
323d0 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
323e0 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
323f0 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
32400 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
32410 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
32420 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
32430 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
32440 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
32450 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
32460 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
32470 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
32480 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
32490 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
324a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
324b0 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
324c0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
324d0 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
324e0 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
324f0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
32500 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
32510 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
32520 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
32530 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
32540 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
32550 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
32560 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
32570 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f  ctions}.** METHO
32580 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
32590 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
325a0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
325b0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
325c0 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
325d0 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
325e0 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
325f0 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65   query.  ^In eve
32600 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
32610 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
32620 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
32630 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
32640 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
32650 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
32660 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
32670 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
32680 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
32690 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
326a0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
326b0 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
326c0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
326d0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
326e0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
326f0 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
32700 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
32710 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
32720 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
32730 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
32740 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
32750 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  ndex 0..** ^The 
32760 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
32770 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
32780 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
32790 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
327a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
327b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
327c0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
327d0 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
327e0 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
327f0 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
32800 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
32810 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
32820 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
32830 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
32840 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
32850 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
32860 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
32870 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
32880 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
32890 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
328a0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
328b0 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
328c0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
328d0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
328e0 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
328f0 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
32900 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
32910 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
32920 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
32930 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
32940 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
32950 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
32960 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
32970 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
32980 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
32990 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
329a0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
329b0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
329c0 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
329d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
329e0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
329f0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
32a00 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
32a10 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
32a20 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
32a30 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
32a40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
32a50 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
32a60 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
32a70 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
32a80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32a90 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
32aa0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
32ab0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
32ac0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
32ad0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
32ae0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
32af0 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
32b00 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
32b10 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
32b20 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
32b30 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
32b40 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
32b50 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
32b60 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
32b70 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
32b80 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
32b90 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
32ba0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
32bb0 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
32bc0 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
32bd0 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
32be0 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
32bf0 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
32c00 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
32c10 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
32c20 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
32c30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
32c40 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
32c50 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
32c60 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
32c70 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
32c80 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
32c90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
32ca0 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
32cb0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
32cc0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
32cd0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
32ce0 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
32cf0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
32d00 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
32d10 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
32d20 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
32d30 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
32d40 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
32d50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
32d60 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
32d70 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
32d80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32d90 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
32da0 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
32db0 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
32dc0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
32dd0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
32de0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
32df0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
32e00 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
32e10 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
32e20 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
32e30 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
32e40 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
32e50 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
32e60 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
32e70 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
32e80 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
32e90 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
32ea0 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
32eb0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
32ec0 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73  _bytes() returns
32ed0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   zero..**.** ^If
32ee0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
32ef0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20   BLOB or UTF-16 
32f00 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
32f10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32f20 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74  ytes16().** rout
32f30 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
32f40 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
32f50 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
32f60 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
32f70 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
32f80 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65  TF-8 string, the
32f90 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
32fa0 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65  _bytes16() conve
32fb0 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
32fc0 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20  g to UTF-16 and 
32fd0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
32fe0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
32ff0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
33000 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
33010 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
33020 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
33030 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  16() uses.** [sq
33040 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
33050 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
33060 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
33070 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72  -16 string and r
33080 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
33090 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
330a0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
330b0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
330c0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
330d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
330e0 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a  es16() returns z
330f0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ero..**.** ^The 
33100 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
33110 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
33120 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
33130 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
33140 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64  umn_bytes16()] d
33150 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  o not include th
33160 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
33170 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  rs at the end.**
33180 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
33190 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74   ^For clarity: t
331a0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
331b0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
331c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
331d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
331e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
331f0 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20   are the number 
33200 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
33210 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
33220 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
33230 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
33240 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
33250 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
33260 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
33270 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33280 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
33290 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
332a0 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  e always zero-te
332b0 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
332c0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
332d0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
332e0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
332f0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
33300 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  B is a NULL poin
33310 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61  ter..**.** <b>Wa
33320 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20  rning:</b> ^The 
33330 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
33340 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
33350 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
33360 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
33370 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
33380 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d   object.  In a m
33390 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e 76  ultithreaded env
333a0 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20  ironment,.** an 
333b0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
333c0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
333d0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
333e0 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a  d safely with.**
333f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
33400 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
33410 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
33420 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
33430 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
33440 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
33450 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
33460 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
33470 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
33480 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
33490 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
334a0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
334b0 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
334c0 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
334d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
334e0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
334f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
33500 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76  es()], the behav
33510 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ior is not threa
33520 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dsafe..**.** The
33530 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
33540 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
33550 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
33560 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f  ppropriate.  ^Fo
33570 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
33580 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
33590 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
335a0 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
335b0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
335c0 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
335d0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
335e0 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
335f0 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
33600 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
33610 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
33620 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
33630 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
33640 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
33650 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
33660 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
33670 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
33680 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
33690 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
336a0 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
336b0 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
336c0 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
336d0 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
336e0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
336f0 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
33700 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
33710 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
33720 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
33730 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
33740 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
33750 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
33760 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
33770 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
33780 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
33790 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  L    <td>   BLOB
337a0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
337b0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
337c0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
337d0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
337e0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
337f0 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
33800 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
33810 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
33820 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
33830 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
33840 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
33850 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
33860 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
33870 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
33880 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
33890 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
338a0 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
338b0 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
338c0 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
338d0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
338e0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
338f0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
33900 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
33910 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
33920 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
33930 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  B    <td> [CAST]
33940 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e   to BLOB.** <tr>
33950 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
33960 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
33970 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
33980 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
33990 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
339a0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41  LOAT    <td> [CA
339b0 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c  ST] to REAL.** <
339c0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
339d0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
339e0 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
339f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
33a00 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
33a10 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
33a20 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
33a30 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
33a40 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
33a50 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
33a60 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  L.** <tr><td>  B
33a70 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
33a80 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
33a90 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
33aa0 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
33ab0 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
33ac0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
33ad0 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
33ae0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
33af0 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
33b00 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
33b10 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
33b20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
33b30 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
33b40 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
33b50 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
33b60 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
33b70 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
33b80 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72  ..** Type conver
33b90 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
33ba0 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
33bb0 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
33bc0 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
33bd0 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
33be0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
33bf0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
33c00 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
33c10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
33c20 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
33c30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
33c40 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
33c50 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
33c60 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
33c70 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
33c80 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
33c90 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
33ca0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
33cb0 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
33cc0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
33cd0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
33ce0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
33cf0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
33d00 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
33d10 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
33d20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
33d30 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
33d40 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
33d50 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
33d60 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
33d70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33d80 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
33d90 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
33da0 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
33db0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
33dc0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
33dd0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
33de0 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
33df0 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72  l>.**.** ^Conver
33e00 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
33e10 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
33e20 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
33e30 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
33e40 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
33e50 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
33e60 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
33e70 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
33e80 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
33e90 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
33ea0 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65  ior pointer refe
33eb0 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65  rences will have
33ec0 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
33ed0 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
33ee0 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
33ef0 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
33f00 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
33f10 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
33f20 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
33f30 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
33f40 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
33f50 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
33f60 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
33f70 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
33f80 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
33f90 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
33fa0 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
33fb0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
33fc0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
33fd0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
33fe0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
33ff0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
34000 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
34010 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
34020 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
34030 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
34040 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34050 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
34060 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
34070 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
34080 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
34090 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
340a0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
340b0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
340c0 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
340d0 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
340e0 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
340f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
34100 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
34110 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
34120 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
34130 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
34140 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
34150 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
34160 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
34170 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
34180 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34190 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
341a0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
341b0 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
341c0 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
341d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
341e0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
341f0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
34200 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
34210 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
34220 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
34230 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
34240 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
34250 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
34260 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
34270 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
34280 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f  )..**.** ^The po
34290 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
342a0 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
342b0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
342c0 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
342d0 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
342e0 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
342f0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
34300 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
34310 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
34320 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
34330 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72  led.  ^The memor
34340 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
34350 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
34360 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
34370 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
34380 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65  .  Do <em>not</e
34390 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  m> pass the poin
343a0 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
343b0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
343c0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
343d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
343e0 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
343f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
34400 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
34410 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
34420 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
34430 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
34440 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
34450 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
34460 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
34470 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
34480 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
34490 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
344a0 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
344b0 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
344c0 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
344d0 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
344e0 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
344f0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
34500 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
34510 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
34520 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
34530 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
34540 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
34550 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
34560 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
34570 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
34580 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
34590 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
345a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
345b0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
345c0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
345d0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
345e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
345f0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
34600 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  I double sqlite3
34610 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
34620 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
34630 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
34640 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
34650 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
34660 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
34670 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
34680 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
34690 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
346a0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
346b0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
346c0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e  ITE_API const un
346d0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
346e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
346f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
34700 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
34710 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
34720 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
34730 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
34740 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
34750 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
34760 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34770 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
34780 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
34790 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
347a0 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
347b0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71  _column_value(sq
347c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
347d0 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
347e0 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
347f0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
34800 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
34810 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  DESTRUCTOR: sqli
34820 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
34830 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
34840 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
34850 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
34860 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
34870 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
34880 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
34890 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
348a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65   the statement e
348b0 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72  ncountered no er
348c0 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68  rors.** or if th
348d0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
348e0 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
348f0 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
34900 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
34910 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
34920 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
34930 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
34940 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
34950 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
34960 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
34970 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
34980 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
34990 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
349a0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
349b0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
349c0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
349d0 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
349e0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
349f0 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
34a00 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
34a10 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
34a20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
34a30 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
34a40 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
34a50 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
34a60 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
34a70 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
34a80 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
34a90 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
34aa0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
34ab0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
34ac0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
34ad0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
34ae0 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
34af0 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
34b00 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
34b10 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
34b20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
34b30 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
34b40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
34b50 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
34b60 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
34b70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
34b80 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
34b90 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
34ba0 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
34bb0 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
34bc0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
34bd0 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
34be0 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
34bf0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
34c00 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
34c10 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
34c20 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
34c30 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
34c40 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
34c50 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
34c60 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
34c70 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
34c80 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
34c90 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
34ca0 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
34cb0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
34cc0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
34cd0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
34ce0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
34cf0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
34d00 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
34d10 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d  ment Object.** M
34d20 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
34d30 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  tmt.**.** The sq
34d40 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
34d50 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
34d60 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65   to reset a [pre
34d70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
34d80 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20  .** object back 
34d90 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
34da0 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62  tate, ready to b
34db0 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a  e re-executed..*
34dc0 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65  * ^Any SQL state
34dd0 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
34de0 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
34df0 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
34e00 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
34e10 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
34e20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
34e30 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
34e40 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
34e50 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
34e60 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
34e70 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
34e80 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  s..**.** ^The [s
34e90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
34ea0 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
34eb0 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
34ec0 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
34ed0 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69  back to the begi
34ee0 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f  nning of its pro
34ef0 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  gram..**.** ^If 
34f00 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
34f10 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
34f20 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
34f30 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
34f40 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
34f50 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
34f60 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
34f70 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71  E],.** or if [sq
34f80 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
34f90 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
34fa0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
34fb0 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74  ,.** then [sqlit
34fc0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
34fd0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
34fe0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
34ff0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
35000 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
35010 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
35020 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
35030 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
35040 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
35050 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
35060 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
35070 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
35080 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
35090 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
350a0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
350b0 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
350c0 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
350d0 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65  * of any [sqlite
350e0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
350f0 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
35100 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
35110 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ] S..*/.SQLITE_A
35120 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  PI int sqlite3_r
35130 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
35140 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
35150 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
35160 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
35170 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  QL Functions.** 
35180 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
35190 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
351a0 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  tines}.** KEYWOR
351b0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
351c0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
351d0 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52  ction}.** KEYWOR
351e0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
351f0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
35200 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f  ctions}.** METHO
35210 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
35220 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
35230 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20  s (collectively 
35240 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69  known as "functi
35250 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
35260 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73  ines").** are us
35270 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
35280 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
35290 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65  gates or to rede
352a0 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
352b0 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67  r.** of existing
352c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
352d0 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
352e0 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
352f0 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ces between.** t
35300 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
35310 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  e the text encod
35320 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72  ing expected for
35330 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
35340 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61  arameter (the na
35350 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  me of the functi
35360 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  on being created
35370 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65  ).** and the pre
35380 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65  sence or absence
35390 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72   of a destructor
353a0 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a   callback for.**
353b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
353c0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a   data pointer..*
353d0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
353e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
353f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35400 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
35410 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
35420 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
35430 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c  ed.  ^If an appl
35440 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72  ication uses mor
35450 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
35460 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
35470 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69  n then applicati
35480 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
35490 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
354a0 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63   added.** to eac
354b0 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
354c0 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79  ction separately
354d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
354e0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
354f0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
35500 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
35510 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a   be created or.*
35520 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54  * redefined.  ^T
35530 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
35540 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
35550 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e   to 255 bytes in
35560 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72   a UTF-8.** repr
35570 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c  esentation, excl
35580 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72  usive of the zer
35590 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  o-terminator.  ^
355a0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
355b0 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d  me.** length lim
355c0 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62  it is in UTF-8 b
355d0 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63  ytes, not charac
355e0 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20  ters nor UTF-16 
355f0 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79  bytes.  .** ^Any
35600 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
35610 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
35620 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
35630 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
35640 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  in [SQLITE_MISUS
35650 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65  E] being returne
35660 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  d..**.** ^The th
35670 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e  ird parameter (n
35680 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e  Arg).** is the n
35690 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
356a0 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
356b0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
356c0 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
356d0 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74  ^If this paramet
356e0 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74  er is -1, then t
356f0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
35700 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
35710 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d  may take any num
35720 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
35730 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
35740 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20  he limit.** set 
35750 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
35760 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
35770 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e  _FUNCTION_ARG]).
35780 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a    If the third.*
35790 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c  * parameter is l
357a0 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67  ess than -1 or g
357b0 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20  reater than 127 
357c0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
357d0 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65  r is.** undefine
357e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
357f0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  urth parameter, 
35800 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66  eTextRep, specif
35810 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c  ies what.** [SQL
35820 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
35830 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
35840 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
35850 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
35860 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20  arameters.  The 
35870 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
35880 6c 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61  ld set this para
35890 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c  meter to.** [SQL
358a0 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20  ITE_UTF16LE] if 
358b0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  the function imp
358c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f  lementation invo
358d0 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  kes .** [sqlite3
358e0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
358f0 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20  )] on an input, 
35900 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
35910 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d  BE] if the.** im
35920 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76  plementation inv
35930 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61  okes [sqlite3_va
35940 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20  lue_text16be()] 
35950 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a  on an input, or.
35960 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
35970 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  ] if [sqlite3_va
35980 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73  lue_text16()] is
35990 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54   used, or [SQLIT
359a0 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72  E_UTF8].** other
359b0 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65  wise.  ^The same
359c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61   SQL function ma
359d0 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
359e0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
359f0 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e  sing.** differen
35a00 74 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  t preferred text
35a10 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68   encodings, with
35a20 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65   different imple
35a30 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a  mentations for.*
35a40 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e  * each encoding.
35a50 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70  .** ^When multip
35a60 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
35a70 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
35a80 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
35a90 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
35aa0 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
35ab0 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
35ac0 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
35ad0 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
35ae0 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sion..**.** ^The
35af0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
35b00 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79  r may optionally
35b10 20 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53   be ORed with [S
35b20 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
35b30 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  TIC].** to signa
35b40 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74  l that the funct
35b50 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ion will always 
35b60 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
35b70 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20  result given.** 
35b80 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20  the same inputs 
35b90 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20  within a single 
35ba0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
35bb0 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  Most SQL functio
35bc0 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d  ns are.** determ
35bd0 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75  inistic.  The bu
35be0 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29  ilt-in [random()
35bf0 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  ] SQL function i
35c00 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
35c10 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68  a.** function th
35c20 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d  at is not determ
35c30 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51  inistic.  The SQ
35c40 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e  Lite query plann
35c50 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a  er is able to.**
35c60 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f   perform additio
35c70 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  nal optimization
35c80 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74  s on determinist
35c90 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f  ic functions, so
35ca0 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b   use.** of the [
35cb0 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
35cc0 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65  STIC] flag is re
35cd0 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20  commended where 
35ce0 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  possible..**.** 
35cf0 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61  ^(The fifth para
35d00 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
35d10 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20  trary pointer.  
35d20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
35d30 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e  on of the.** fun
35d40 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61  ction can gain a
35d50 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f  ccess to this po
35d60 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c  inter using [sql
35d70 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
35d80 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ].)^.**.** ^The 
35d90 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61  sixth, seventh a
35da0 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65  nd eighth parame
35db0 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74  ters, xFunc, xSt
35dc0 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61  ep and xFinal, a
35dd0 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  re.** pointers t
35de0 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e  o C-language fun
35df0 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c  ctions that impl
35e00 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
35e10 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
35e20 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61  regate. ^A scala
35e30 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
35e40 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
35e50 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
35e60 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61   xFunc.** callba
35e70 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f  ck only; NULL po
35e80 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70  inters must be p
35e90 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
35ea0 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
35eb0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e   parameters. ^An
35ec0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
35ed0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
35ee0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
35ef0 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61  on of xStep.** a
35f00 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55  nd xFinal and NU
35f10 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20  LL pointer must 
35f20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
35f30 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20  unc. ^To delete 
35f40 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53  an existing.** S
35f50 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
35f60 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e  ggregate, pass N
35f70 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72  ULL pointers for
35f80 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74   all three funct
35f90 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73  ion.** callbacks
35fa0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65  ..**.** ^(If the
35fb0 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
35fc0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
35fd0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
35fe0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a   is not NULL,.**
35ff0 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74   then it is dest
36000 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61  ructor for the a
36010 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
36020 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65  pointer. .** The
36030 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69   destructor is i
36040 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
36050 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65  function is dele
36060 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62  ted, either by b
36070 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64  eing.** overload
36080 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64  ed or when the d
36090 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
360a0 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20  on closes.)^.** 
360b0 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
360c0 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20  is also invoked 
360d0 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  if the call to.*
360e0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
360f0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66  _function_v2() f
36100 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74  ails..** ^When t
36110 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61  he destructor ca
36120 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65  llback of the te
36130 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  nth parameter is
36140 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20   invoked, it.** 
36150 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67  is passed a sing
36160 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
36170 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  h is a copy of t
36180 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
36190 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ata .** pointer 
361a0 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69  which was the fi
361b0 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  fth parameter to
361c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
361d0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a  function_v2()..*
361e0 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d  *.** ^It is perm
361f0 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65  itted to registe
36200 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  r multiple imple
36210 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
36220 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69  e same.** functi
36230 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  ons with the sam
36240 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20  e name but with 
36250 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67  either differing
36260 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61   numbers of.** a
36270 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66  rguments or diff
36280 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20  ering preferred 
36290 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20  text encodings. 
362a0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
362b0 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
362c0 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73  ntation that mos
362d0 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
362e0 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
362f0 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
36300 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20  nction is used. 
36310 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70   ^A function imp
36320 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
36330 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a   a non-negative.
36340 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65  ** nArg paramete
36350 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61  r is a better ma
36360 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
36370 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
36380 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67  on with.** a neg
36390 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20  ative nArg.  ^A 
363a0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
363b0 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78  he preferred tex
363c0 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61  t encoding.** ma
363d0 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61  tches the databa
363e0 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61  se encoding is a
363f0 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68   better.** match
36400 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
36410 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
36420 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
36430 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69  .  .** ^A functi
36440 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
36450 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
36460 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31   is between UTF1
36470 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a  6le and UTF16be.
36480 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d  ** is a closer m
36490 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
364a0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
364b0 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
364c0 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e  ce is.** between
364d0 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e   UTF8 and UTF16.
364e0 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e  .**.** ^Built-in
364f0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
36500 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20  e overloaded by 
36510 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  new application-
36520 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
36530 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70  s..**.** ^An app
36540 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36550 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72   function is per
36560 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f  mitted to call o
36570 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
36580 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65  nterfaces.  Howe
36590 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20  ver, such calls 
365a0 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73  must not.** clos
365b0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
365c0 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69  onnection nor fi
365d0 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20  nalize or reset 
365e0 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  the prepared.** 
365f0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69  statement in whi
36600 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ch the function 
36610 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53  is running..*/.S
36620 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
36630 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
36640 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
36650 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
36660 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
36670 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
36680 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
36690 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
366a0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
366b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
366c0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
366d0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
366e0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
366f0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
36700 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
36710 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
36720 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
36730 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
36740 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
36750 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
36760 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
36770 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
36780 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
36790 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
367a0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
367b0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
367c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
367d0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
367e0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
367f0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
36800 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
36810 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
36820 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
36830 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36840 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
36850 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
36860 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a  te_function_v2(.
36870 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
36880 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
36890 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
368a0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
368b0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
368c0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
368d0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
368e0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
368f0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
36900 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
36910 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
36920 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
36930 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
36940 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
36950 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  text*),.  void(*
36960 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
36970 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
36980 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69  REF: Text Encodi
36990 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ngs.**.** These 
369a0 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
369b0 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
369c0 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
369d0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
369e0 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
369f0 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
36a00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
36a10 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
36a20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d   1    /* IMP: R-
36a30 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23  37514-35566 */.#
36a40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
36a50 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 20 20  F16LE        2  
36a60 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37    /* IMP: R-0337
36a70 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69  1-37637 */.#defi
36a80 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
36a90 45 20 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a  E        3    /*
36aa0 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34   IMP: R-51971-34
36ab0 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  154 */.#define S
36ac0 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
36ad0 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
36ae0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
36af0 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
36b00 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
36b10 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72      5    /* Depr
36b20 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e  ecated */.#defin
36b30 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
36b40 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
36b50 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
36b60 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
36b70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36b80 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73  : Function Flags
36b90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
36ba0 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52  stants may be OR
36bb0 65 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 68  ed together with
36bc0 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
36bd0 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 65  _UTF8 | preferre
36be0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  d text encoding]
36bf0 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61   as the fourth a
36c00 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73  rgument.** to [s
36c10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
36c20 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  nction()], [sqli
36c30 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
36c40 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
36c50 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36c60 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  function_v2()]..
36c70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
36c80 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20  E_DETERMINISTIC 
36c90 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20     0x800../*.** 
36ca0 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
36cb0 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
36cc0 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
36cd0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
36ce0 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
36cf0 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
36d00 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
36d10 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
36d20 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
36d30 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
36d40 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
36d50 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
36d60 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
36d70 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
36d80 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
36d90 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
36da0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
36db0 65 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61  encourage progra
36dc0 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a  mmers to avoid.*
36dd0 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * these function
36de0 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65  s, we will not e
36df0 78 70 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79  xplain what they
36e00 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20   do..*/.#ifndef 
36e10 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52  SQLITE_OMIT_DEPR
36e20 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50  ECATED.SQLITE_AP
36e30 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
36e40 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
36e50 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
36e60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36e70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
36e80 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
36e90 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
36ea0 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
36eb0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
36ec0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
36ed0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
36ee0 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
36ef0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
36f00 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
36f10 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
36f20 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
36f30 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
36f40 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
36f50 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
36f60 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73  EPRECATED void s
36f70 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
36f80 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
36f90 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
36fa0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
36fb0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
36fc0 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
36fd0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
36fe0 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20  nt),.           
36ff0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a             void*
37000 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
37010 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
37020 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
37030 6e 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a  ng SQL Values.**
37040 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
37050 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65  _value.**.** The
37060 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
37070 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
37080 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
37090 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
370a0 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
370b0 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
370c0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
370d0 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
370e0 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
370f0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
37100 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  .  .**.** The xF
37110 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
37120 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
37130 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
37140 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
37150 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
37160 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
37170 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
37180 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
37190 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
371a0 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
371b0 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
371c0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
371d0 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
371e0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
371f0 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
37200 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
37210 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
37220 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
37230 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
37240 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
37250 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
37260 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
37270 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
37280 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
37290 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
372a0 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
372b0 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
372c0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
372d0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
372e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
372f0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
37300 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
37310 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
37320 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
37330 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
37340 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
37350 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
37360 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
37370 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
37380 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
37390 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  ehavior..**.** ^
373a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
373b0 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
373c0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
373d0 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
373e0 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
373f0 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72  ept that these r
37400 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
37410 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
37420 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
37430 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
37440 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
37450 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
37460 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
37470 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
37480 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
37490 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
374a0 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
374b0 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
374c0 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
374d0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
374e0 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
374f0 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
37500 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
37510 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
37520 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
37530 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
37540 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
37550 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
37560 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
37570 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
37580 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
37590 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
375a0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
375b0 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
375c0 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
375d0 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
375e0 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
375f0 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
37600 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
37610 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
37620 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
37630 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
37640 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
37650 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
37660 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
37670 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
37680 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
37690 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
376a0 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
376b0 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
376c0 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
376d0 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
376e0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
376f0 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
37700 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
37710 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
37720 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
37730 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
37740 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
37750 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
37760 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
37770 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
37780 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
37790 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
377a0 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
377b0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
377c0 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
377d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
377e0 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
377f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
37800 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
37810 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
37820 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
37830 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
37840 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
37850 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
37860 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
37870 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
37880 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
37890 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
378a0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
378b0 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
378c0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
378d0 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
378e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
378f0 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
37900 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
37910 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
37920 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
37930 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
37940 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
37950 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
37960 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
37970 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
37980 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37990 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
379a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
379b0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
379c0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
379d0 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
379e0 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
379f0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
37a00 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
37a10 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
37a20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37a30 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
37a40 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
37a50 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
37a60 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
37a70 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75  LITE_API const u
37a80 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
37a90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
37aa0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
37ab0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
37ac0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
37ad0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
37ae0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
37af0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
37b00 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
37b10 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
37b20 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
37b30 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
37b40 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
37b50 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
37b60 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
37b70 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
37b80 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
37b90 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37ba0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
37bb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
37bc0 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
37bd0 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
37be0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
37bf0 69 6e 67 20 54 68 65 20 53 75 62 74 79 70 65 20  ing The Subtype 
37c00 4f 66 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a  Of SQL Values.**
37c10 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
37c20 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65  _value.**.** The
37c30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73   sqlite3_value_s
37c40 75 62 74 79 70 65 28 56 29 20 66 75 6e 63 74 69  ubtype(V) functi
37c50 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  on returns the s
37c60 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a 20 61 6e  ubtype for.** an
37c70 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
37c80 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
37c90 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20 56 2e 20  on] argument V. 
37ca0 20 54 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20   The subtype.** 
37cb0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63 61 6e 20  information can 
37cc0 62 65 20 75 73 65 64 20 74 6f 20 70 61 73 73 20  be used to pass 
37cd0 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f 75 6e 74  a limited amount
37ce0 20 6f 66 20 63 6f 6e 74 65 78 74 20 66 72 6f 6d   of context from
37cf0 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66 75 6e 63  .** one SQL func
37d00 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68 65 72 2e  tion to another.
37d10 20 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74    Use the [sqlit
37d20 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 70  e3_result_subtyp
37d30 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  e()].** routine 
37d40 74 6f 20 73 65 74 20 74 68 65 20 73 75 62 74 79  to set the subty
37d50 70 65 20 66 6f 72 20 74 68 65 20 72 65 74 75 72  pe for the retur
37d60 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51  n value of an SQ
37d70 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  L function..**.*
37d80 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 6e  * SQLite makes n
37d90 6f 20 75 73 65 20 6f 66 20 73 75 62 74 79 70 65  o use of subtype
37da0 20 69 74 73 65 6c 66 2e 20 20 49 74 20 6d 65 72   itself.  It mer
37db0 65 6c 79 20 70 61 73 73 65 73 20 74 68 65 20 73  ely passes the s
37dc0 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f 6d 20 74  ubtype.** from t
37dd0 68 65 20 72 65 73 75 6c 74 20 6f 66 20 6f 6e 65  he result of one
37de0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
37df0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
37e00 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  on] into the.** 
37e10 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74 68 65 72  input of another
37e20 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
37e30 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 71 6c  unsigned int sql
37e40 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79  ite3_value_subty
37e50 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
37e60 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
37e70 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 20 46 72  REF: Copy And Fr
37e80 65 65 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a  ee SQL Values.**
37e90 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
37ea0 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  _value.**.** ^Th
37eb0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
37ec0 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65  dup(V) interface
37ed0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
37ee0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
37ef0 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 44  lue].** object D
37f00 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
37f10 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 63  ointer to that c
37f20 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  opy.  ^The [sqli
37f30 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 74 75 72  te3_value] retur
37f40 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70 72 6f  ned.** is a [pro
37f50 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
37f60 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65 76 65  alue] object eve
37f70 6e 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 69  n if the input i
37f80 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  s not..** ^The s
37f90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
37fa0 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (V) interface re
37fb0 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 56 20  turns NULL if V 
37fc0 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20 61 0a  is NULL or if a.
37fd0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
37fe0 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  tion fails..**.*
37ff0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
38000 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 6e 74  alue_free(V) int
38010 65 72 66 61 63 65 20 66 72 65 65 73 20 61 6e 20  erface frees an 
38020 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
38030 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76 69 6f  object.** previo
38040 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
38050 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
38060 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66 20 56  e_dup()].  ^If V
38070 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
38080 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  er.** then sqlit
38090 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29  e3_value_free(V)
380a0 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
380b0 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  o-op..*/.SQLITE_
380c0 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  API sqlite3_valu
380d0 65 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e *sqlite3_value
380e0 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c 69 74  _dup(const sqlit
380f0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
38100 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
38110 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 73  te3_value_free(s
38120 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
38130 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
38140 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
38150 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
38160 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  xt.** METHOD: sq
38170 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
38180 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  .** Implementati
38190 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
381a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
381b0 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
381c0 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
381d0 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
381e0 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
381f0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
38200 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
38210 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
38220 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
38230 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
38240 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
38250 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
38260 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
38270 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
38280 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
38290 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
382a0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
382b0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
382c0 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
382d0 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
382e0 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
382f0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
38300 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
38310 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
38320 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
38330 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
38340 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
38350 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
38360 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
38370 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
38380 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
38390 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
383a0 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
383b0 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
383c0 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
383d0 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
383e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
383f0 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
38400 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
38410 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
38420 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
38430 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
38440 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
38450 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
38460 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
38470 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
38480 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
38490 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
384a0 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
384b0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
384c0 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
384d0 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
384e0 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
384f0 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
38500 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
38510 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
38520 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
38530 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
38540 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a   NULL pointer .*
38550 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c  * when first cal
38560 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73  led if N is less
38570 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
38580 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
38590 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
385a0 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
385b0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
385c0 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
385d0 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
385e0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
385f0 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
38600 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
38610 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
38620 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
38630 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
38640 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
38650 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
38660 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
38670 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
38680 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
38690 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
386a0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
386b0 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
386c0 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
386d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20   allocation.)^  
386e0 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61  Within the xFina
386f0 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69  l callback, it i
38700 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73  s customary to s
38710 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c  et.** N=0 in cal
38720 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ls to sqlite3_ag
38730 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
38740 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20  C,N) so that n